# Pdftools Documentation > Technical documentation of the main Pdftools products, such as Pdftools SDK, Conversion Service, PDF Viewer SDK, and other legacy SDKs and products. This documentation also includes links to various API references and resources. This file contains all documentation content in a single document following the llmstxt.org standard. ## Conversion Service The Conversion Service is a comprehensive on-premise solution for automating your document processes. It takes input documents of different formats from multiple sources and processes them according to your use case to produce high-quality PDF/A documents. The robust client-server architecture of the Conversion Service provides high availability and stability, allowing you to access the service through powerful REST APIs over HTTP or HTTPS. **tip: To learn more about how you can convert documents as part of an automated document workflow, see [how the Conversion Service works](https://www.pdf-tools.com/docs/conversion-service/configure/how-cs-works).** ## Key features - **High throughput** job processing - Specialized **workflows**: Archive as PDF/A-2, Archive as PDF/A-3, Archive as PDF/A-1, Convert to PDF, Prepare Invoice PDF, Create Dossier PDF - **Configuration profiles** for each workflow - Convenient **Conversion Service Configurator** - **Watched folder**: Convert all files included in a folder you specify using your configured workflow - **Statistics**: Activity and job processing information - **Logging** and **monitoring** - API integration with **Advanced API** or **Simple API** ## Compatible operating systems The Conversion Service is available for the following operating systems: **Windows version:** | Version | Bit version | | ------------------- | ----------- | | Windows Server 2019 | x64 | | Windows Server 2022 | x64 | | Windows Server 2025 | x64 | **Docker version:** | Containerization tool | Minimal required version | | ---------------------- | ------------------------- | | Docker | 20.10 or later | | Docker Compose | 1.27 or later | | Linux distributions and toolchains | Bit version | | ----------------- | ----------- | | Red Hat | x64 | | CentOS | x64 | | Oracle Linux 8+ | x64 | | Fedora 29+ | x64 | | Debian 10+ | x64 | | Linux kernel 2.6+ | x64 | | GCC Toolset 4.8+ | x64 | | glibc 2.27+ | x64 | **important: - The Conversion Service includes a Standard Converter for Microsoft Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files that works without additional configuration or licensing.** - For highest visual fidelity, configure a [local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation) or the [Office for the web service](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#office-for-the-web-service). ## Hardware requirements The Conversion Service has the following hardware requirements: | Components | Minimal | Recommended | | -------------------- | ------------------------- |------------------------- | | CPU | 1.4 GHz 64-bit processor | 2.5 GHz 64-bit processor | | RAM | 4 GB | 8 GB | | Storage space | 32 GB | 64 GB | | Network Interface | - | Gigabit Ethernet | **info: - A multi-core processor is preferable for optimal performance.** - Use an SSD to boost the performance as the Conversion Service heavily relies on input and output operations. :::note[Optimal hardware requirements] The optimal performance of the Conversion Service varies depending on the tasks you want it to perform and how fast you need it to process the results. ## Network and security recommendations ### Antivirus Use Windows Defender. Third-party antivirus software can adversely affect the performance of the Conversion Service. Exclude specific folders and processes from Windows Defender or any third-party security software checks that can affect the performance of the service. | Excluded | Path | |-----------|--------------------------------------------------------------------------------------------------| | Folder | `INSTALLATION_PATH\Pdftools\Conversion Service` | | Folder | `INSTALLATION_PATH\Pdftools\Conversion Service\Logs` | | Processes | `INSTALLATION_PATH\Pdftools\Conversion Service\bin\*` | | Processes | `C:\Program Files\Microsoft Office\Root\Office16\*` | - Replace the `INSTALLATION_PATH` with the installation path of the Conversion Service on your system. ### Firewall configuration The Pdftools support and warranty cover issues up to the firewall level. If a firewall interferes with the Conversion Service, it's beyond the scope of Pdftools support. If the service works with the firewall turned off or on a local machine, any issues arising due to firewall configuration are your responsibility. | Rule | Port | |----------|----------------------------------------------------------------------------------| | Inbound | 13033 for HTTP/HTTPS | | Inbound | 13034 for HTTP/HTTPS | | Inbound | 9999 for HTTP | | Outbound | Integration related ports (for example, REST Output, Mailbox-related Connectors) | ### Data encryption standards Ensure limited access to the machine because the files stored on the system aren't encrypted. Configure HTTPS to encrypt the data that is exchanged and to ensure the data integrity. ### Access controls To use the Conversion Service Configurator on Windows Server, you need to have administrator rights. For the Microsoft Office file conversion, use the user account of Microsoft Office with regular user permissions and also **Log on as a batch job** and **Allow log on locally** security policies. ## Input formats The Conversion Service supports a variety of input formats: - PDF - Raster image formats (JPEG, PNG, GIF, TIFF, BMP, JBIG2, JPEG2000, HEIC, HEIF, WebP, JFIF) - Microsoft Word binary formats (DOC, DOT) - Microsoft Word OOXML-based formats (DOCX, DOCM, DOTX, DOTM) - WordML or WordprocessingML (XML) - Microsoft Excel binary formats (XLS, XLT) - Microsoft Excel OOXML-based formats (XLSX, XLSM, XLTX, XLTM) - SpreadsheetML (XML) - Microsoft PowerPoint binary formats (PPT, PPS) - Microsoft PowerPoint OOXML-based formats (PPTX, PPTM, PPSX, PPSM) - Open Document Text (ODT) - Open Document Spreadsheet (ODS) - Open Document Presentation (ODP) - MIME-email (EML) - S/MIME signed email (P7M) - Outlook-email (MSG) - ZIP archive - Plain text (TXT) - Rich text (RTF) - Comma-separated values (CSV) - Document-like HTML **note: However, the Conversion Service does not support PDF with XFA forms (Adobe Lifecycle), JPEG2000 compound image (JPM), MS Project, MS Visio, RAR-Archive, Website-Archive (MHT, HTMZIP), URL as a file format, Metafile (EMF), XPS as input formats and custom formats (Plugins).** ## Output formats The Conversion Service can convert input files to the following output formats: - PDF/A-1 - PDF/A-2 - PDF/A-3 - Plain PDF (1.x) - TIFF ## API overview Automate documentation workflows and processes by using one of the two Conversion Service APIs: - **[Simple API](#simple-api)**: Process files in one API call. The Simple API is designed to solve common use cases of the conversion process. - **[Advanced API](#advanced-api)**: Leverage fine-grained control over the conversion process, letting you convert many documents in bulk and check their status during the conversion process. Reliably process the harmonization of documents from multiple sources and prepare them optimally for your intended purpose. ### Simple API The examples of the Simple API use cases include the following: - Convert files with one API call. - Convert documents one by one with a blocking call until the API delivers the converted PDF. - Integrate the Conversion Service with multiple applications with a dedicated API for each application. Each application can include different workflows and profiles. - Convert large files (larger than 100 MB) using the plain HTTP input endpoint of the Simple API. ### Advanced API The examples of Advanced API use cases include the following: - Merge hundreds of documents into a single PDF using the Create Dossier PDF workflow. - List and monitor all jobs processed, workflows, and profiles on your server. - Track and monitor the status of the Conversion Service to make sure that everything is running correctly. - Store the results of the conversion on Amazon S3, Azure Blob Storage, or SharePoint and choose the destination location on the fly. - Collect all the files over time and wait until all documents are ready to convert. Create a job, add files over time, and then start the conversion job. - Convert large files (larger than 100 MB). ## Supported releases For information about the Conversion Service LTS releases that provide you with Pdftools full support, review [Supported LTS product releases](https://www.pdf-tools.com/docs/support/release-management/#supported-lts-product-releases) section. --- ## Conversion Service API references Learn about the Conversion Service APIs and how to use them. Integrate and automate complex file processing pipelines using a locally hosted API. Use these APIs to automate your document processes. Harmonize documents from various sources and prepare them optimally for your intended purpose. Substitute inefficient and error-prone manual steps with reliable automated processing. The Conversion Service provides two APIs that you can use to automate documentation workflows and processes: - **Simple API**: Process files in one API call. This API simplifies the functionality of the Advanced API. - **Advanced API**: Leverage fine-grained control over the conversion process, letting you convert many documents in bulk and check their status during the conversion process. Reliably process the harmonization of documents from various sources and prepare them optimally for your intended purpose. **tip: Find use cases and learn how to get started with both of the APIs in the **[API getting started](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/)** guide.** ## Postman collections Use the following Postman collections: - [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json) - [Advanced API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_advanced_api.postman_collection.json) ## OpenAPI specifications Download the OpenAPI specification files: - [Simple API OpenAPI specification](https://www.pdf-tools.com/docs/files/conversion-service/simple_api_openapi.yaml) - [Advanced API OpenAPI specification](https://www.pdf-tools.com/docs/files/conversion-service/advanced_api_openapi.yaml) --- ## Add data to job `post` `/jobs/{jobId}/data/` Add data such as documents, images, and other accepted files for processing. Use the query parameter `"url"` with the `"application/json"` or `"application/xml"` content. When you add document options, follow the correct JSON structure. Example: Using the `DOC.PASSWORD` option: ```json [ { "name": "DOC.PASSWORD", "value": "Replace with your password as a string." } ] ``` After you add all data to the job and send the `addData` request, send the `startJob` API request. Request --- ## Advanced API Gain fine-grained control over the conversion process, letting you convert many documents in bulk and check their status during the conversion process. Reliably process the harmonization of documents from various sources and prepare them optimally for your intended purpose. The Advanced API also lets you convert files larger than 100 MB with no upper size limit. --- ## Cancel job `post` `/jobs/{jobId}:cancel` Cancel the processing of a job. This request has no effect if a job has not been started or has already finished. If the job has already finished, its result is not affected by `cancelJob`. The job's result can still be requested using `getJobResult`. If the job's result is not required anymore, `cancelJob` is optional. Instead, the job can simply be deleted using `deleteJob`. Request --- ## Create new job `post` `/jobs/` Create a new job for processing using the provided `workflow` and `profile`. To get a full list of available workflows, call the [List available workflows](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/list-workflows) endpoint. After you create a job, use the `addData` API request to add data such as documents, images, and other accepted files for processing. Delete all created jobs when they are finished using the `deleteJob` request. Note that there are two types of options that you can use: - **Job options**: Set in the body of the `createJob` API request. - **Document options**: Set in the `addData` API request. Request --- ## Delete job `delete` `/jobs/{jobId}` When the job processing is completed, delete the job and all associated resources using `deleteJob` API request. If you delete the job, you can create new jobs. Jobs that you don't delete explicitly are automatically deleted after a timeout or when the service is shut down. You can delete a job regardless of its status. Jobs with a `processing` status are canceled automatically before deletion. Request --- ## Get job info `get` `/jobs/{jobId}` Get job info. Request --- ## Get job result data `get` `/jobs/{jobId}/result/{resultId}` Get result data, typically a document, of a job that has completed successfully. Request --- ## Get job result `get` `/jobs/{jobId}/result` This request returns the result when it is available and is blocked otherwise. You can also call the `getJobInfo` API request until the returned job status is `completed`. When the job is completed successfully, retrieve the result data with the `getJobResultData` API request. Note that when waiting for the job result, request timeouts can occur after 2 minutes by default. You can configure the job and task timeouts in the Conversion Service Configurator under **Workflows & Profiles**. Select a workflow profile and adjust the values in the **Job Settings** section. It is recommended to handle request timeouts, especially for long-running jobs or for services under high load. Request --- ## Get the service status `get` `/` Get the service status. --- ## List all jobs `get` `/jobs/` List all jobs and their statuses. --- ## List available workflows `get` `/workflows` List available workflows. --- ## Start job `post` `/jobs/{jobId}:start` Signal that all data was added to a job and the Conversion Service API can start processing it. The `startJob` request activates the document merge and post-processing steps. After starting a job, send the `getJobResult` API request. Request --- ## Store job result data `post` `/jobs/{jobId}/result/{resultId}:{storeMethod}` Store the result data by sending it to a web server via HTTP(S) request. Request --- ## Archive PDF/A-2 Outputs PDFs in the **PDF/A-2 archival standard**. This is the recommended archival format for long-term document preservation. ## Connection ID ``` archive-pdfa2-default ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/archive-pdfa2-default` - **JSON input:** `POST {baseURL}/http.inputstructured/archive-pdfa2-default` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Example (JSON) ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ] } ``` This profile doesn't require specific job options. --- ## Archive PDF/A-3 Outputs PDFs in the **PDF/A-3 archival standard**, recommended especially for specific cases such as **electronic invoicing (e-invoices)**. ## Connection ID ``` archive-pdfa3-default ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/archive-pdfa3-default` - **JSON input:** `POST {baseURL}/http.inputstructured/archive-pdfa3-default` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Example (JSON) ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ] } ``` This profile doesn't require specific job options. --- ## All to PDF Profile Converts **any supported input document** into a standard PDF. ## Connection ID ``` convert-to-pdf ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/convert-to-pdf` - **JSON input:** `POST {baseURL}/http.inputstructured/convert-to-pdf` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Example (JSON) ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ] } ``` This profile doesn't require specific job options. --- ## Merge Profile Merges **multiple documents into a single PDF dossier**. ## Connection ID ``` dossier-default ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/dossier-default` - **JSON input:** `POST {baseURL}/http.inputstructured/dossier-default` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Example (JSON) ```json { "name": "merge-documents", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "document1.pdf" }, { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "document2.pdf" } ] } ``` This profile doesn't require specific job options. --- ## Ready for Email PDF/A-2 Outputs PDFs in the **PDF/A-2 archival standard**, optimized specifically for **email distribution**. ## Connection ID ``` archive-pdfa2-email-optimization ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/archive-pdfa2-email-optimization` - **JSON input:** `POST {baseURL}/http.inputstructured/archive-pdfa2-email-optimization` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Optimization option When using the JSON endpoint, include the `OPTIMIZEPROFILE` job option: ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ], "options": [ { "name": "OPTIMIZEPROFILE", "value": "max" } ] } ``` | Option | Value | |---|---| | `OPTIMIZEPROFILE` | `max` | --- ## Ready for Web PDF/A-2 Outputs PDFs in the **PDF/A-2 archival standard**, optimized specifically for **web viewing**. ## Connection ID ``` archive-pdfa2-web-optimization ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/archive-pdfa2-web-optimization` - **JSON input:** `POST {baseURL}/http.inputstructured/archive-pdfa2-web-optimization` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Optimization option When using the JSON endpoint, include the `OPTIMIZEPROFILE` job option: ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ], "options": [ { "name": "OPTIMIZEPROFILE", "value": "web" } ] } ``` | Option | Value | |---|---| | `OPTIMIZEPROFILE` | `web` | --- ## Ready to Print PDF/A-2 Outputs PDFs in the **PDF/A-2 archival standard**, optimized specifically for **printing**. ## Connection ID ``` archive-pdfa2-print-optimization ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/archive-pdfa2-print-optimization` - **JSON input:** `POST {baseURL}/http.inputstructured/archive-pdfa2-print-optimization` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Optimization option When using the JSON endpoint, include the `OPTIMIZEPROFILE` job option: ```json { "name": "file-conversion", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "hello_world.txt" } ], "options": [ { "name": "OPTIMIZEPROFILE", "value": "print" } ] } ``` | Option | Value | |---|---| | `OPTIMIZEPROFILE` | `print` | --- ## Repair Profile Converts any supported document to PDF, then **validates and repairs** the resulting PDF. ## Connection ID ``` repair-pdf ``` ## Endpoints Use this connection ID with the Simple API endpoints: - **Binary upload:** `POST {baseURL}/http.input/repair-pdf` - **JSON input:** `POST {baseURL}/http.inputstructured/repair-pdf` See the [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-plain-http) and [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json) endpoint reference for request and response details. ## Example (JSON) ```json { "name": "file-repair", "data": [ { "content": "SGVsbG8gd29ybGQuCg==", "fileName": "document.pdf" } ] } ``` This profile doesn't require specific job options. --- ## REST input JSON `post` `/http.inputstructured/{connectionID}` Submit files for conversion using structured JSON input. Upload documents using a URL or in Base64-encoded format. This endpoint supports structured input and output, including job options and metadata. The `connectionID` path parameter determines which pre-installed or custom Connection to use. For available values, refer to [Pre-installed connections](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api#pre-installed-connections). Request --- ## REST input plain HTTP `post` `/http.input/{connectionID}` Submit a file for conversion using a binary upload. This endpoint supports large files (larger than 100 MB). Provide the file as `multipart/form-data` in the request body. The `connectionID` path parameter determines which pre-installed or custom Connection to use. For available values, refer to [Pre-installed connections](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api#pre-installed-connections). Request --- ## Simple API Process files in one API call. Convert documents individually with a blocking call until the API delivers the converted files. Implement the Conversion Service with multiple applications, each with a dedicated API. Each application can include different Workflows and Profiles. Convert large files (larger than 100 MB) using the plain HTTP input endpoint of the Simple API. By default, the Simple API operates synchronously, blocking until the conversion completes and returning the result in the response. If the **Response** setting in the REST Input Connector configuration is set to **Immediately**, the API returns a `202 Accepted` status and processes the file asynchronously. In this case, results are delivered through the configured output connectors. ## Pre-installed connections The Conversion Service comes with the following pre-installed Connections that you can use out of the box. Replace the `{connectionID}` path parameter in the endpoint URL with one of these values: | Connection ID | Profile | Description | |---|---|---| | `archive-pdfa2-default` | Archive PDF/A-2 | Outputs PDFs in the PDF/A-2 archival standard (recommended) | | `archive-pdfa3-default` | Archive PDF/A-3 | Outputs PDFs in the PDF/A-3 archival standard (for specific cases, such as e-invoices) | | `convert-to-pdf` | All to PDF | Converts any supported input document into a standard PDF | | `dossier-default` | Merge | Merges multiple documents into a single PDF dossier | | `archive-pdfa2-print-optimization` | Ready to Print PDF/A-2 | PDF/A-2 archival standard with print optimization | | `archive-pdfa2-web-optimization` | Ready for Web PDF/A-2 | PDF/A-2 archival standard with web optimization | | `archive-pdfa2-email-optimization` | Ready for Email PDF/A-2 | PDF/A-2 archival standard with email optimization | | `repair-pdf` | Repair | Converts any supported document to PDF and validates and repairs the output | You can also create custom Connections in the **Conversion Service Configurator** and use their Connection IDs with these endpoints. ### Optimization options The Ready to Print, Ready for Web, and Ready for Email profiles accept an `OPTIMIZEPROFILE` job option in the JSON request body: | Profile | `OPTIMIZEPROFILE` value | |---|---| | Ready to Print PDF/A-2 | `print` | | Ready for Web PDF/A-2 | `web` | | Ready for Email PDF/A-2 | `max` | --- ## Configure the Conversion Service To get up and running with the Conversion Service, you need to configure: - Service - Profiles - Office conversion ## Configuring the service You can configure the service itself in two ways depending on your installation: - **[Configurator](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service)**: a program added to the Windows Start menu during installation lets you determine the service's configuration using an easy interface. - **[Environmental values](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container)**: if you are using a Docker container, you pass environmental values at startup. ## Configuring profiles A profile defines the options and settings used for [pre-defined workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/). To change the options associated with a profile, you need to [configure profiles](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). ## Configuring Office conversion The Conversion Service converts Word, Excel, and PowerPoint files to PDF by default using the [Standard Converter](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#standard-converter-default). For highest visual fidelity, see [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). To convert Microsoft Word files that include tracked changes (revisions, also called redlining), review [Configure conversion of redlined Microsoft Word documents](https://www.pdf-tools.com/docs/conversion-service/configure/word-track-changes). --- ## Configure connections Integrate the Conversion Service into your environment by connecting input sources (for example a watched folder) to output destinations (for example an output folder) and configure how documents will be processed. To achieve this configure a connection using the Conversion Service Configurator, which is installed with the Conversion Service. ## Set up a connection A connection defines how the Conversion Service is integrated into an existing system. Each connection requires [input and output connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/). To add and configure a new connection click the **Add Connection** button. To edit or delete an existing connection, click on the respective icon. To copy an existing connection, click the Copy icon. - **Name (required)**: Enter a connection name. - **Description (optional)**: Enter a connection description. - **Input(s) (required)**: Configure an input connector by clicking **Add**. - **Processing (required)**: Select the workflow and profile for the conversion. - **Output(s) (required)**: Configure an output connector by clicking **Add**. ## Add a connector Click **Add** in the desired section to add an input or output connector. | Connector type | Connector | Description | |---|---|--| | **Input** | [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-json)| Convert files sent in the request body in JSON format, either as a single file or multiple files. | | | [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http)| Convert files sent in the request body in HTTP format, either as a single file or multiple files. | | | [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder)| Convert all files placed into a configurable input directory. | | | [Watched Mailbox (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-exchange-online) | Convert all emails that are placed into a configurable Microsoft Exchange Online mailbox. | | | [Watched Mailbox (IMAP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-imap)| Convert all emails that are placed into a configurable IMAP mailbox. | | **Output** | [Create Text file](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#create-text-file) | Create a text file with additional information. | | | [Execute Command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command) | Execute a configurable command with arguments on the files. | | | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) | Copy files into a configurable output directory. | | | [Output Mailbox (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-exchange-online) | Copy files to a configurable mailbox on a Microsoft Exchange Online server. | | | [Output Mailbox (IMAP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-imap) | Copy files to a configurable mailbox on an IMAP server. | | | [REST Output](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-output-connectors#rest-output) | Post files as a multipart/form-data request to a configurable output URL. | | | [Send Email (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-exchange-online) | Send an email to a configurable recipient using a Microsoft Exchange Online server. | | [Send Email (SMTP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-smtp) | Send an email to a configurable recipient using an SMTP server. Select the desired connector and click **Next** to confirm the selection. ## Configure connectors Set options for the selected connector. A summary for each option is documented with tooltips. For a detailed explanation of the connector, click on the title to open the documentation panel. :::info[Important] You must restart the Conversion Service for any configuration changes to take effect. When you add or edit connections, the Configurator detects changes and displays an unobtrusive notification. For your convenience, your changes are kept in memory until you click **Save & Restart Service**. ## Configure connectors in Docker To configure connectors in Docker: 1. Use the Configurator UI to add connections and input or output connectors as described in the previous sections. 2. The changes are storred in the `Connections.xml` file in the installation folder. 3. Map the file from the host to `/etc/connsrv/Connections.xml` in the container. 4. Set the `IMPORT_CONNECTIONS` environment variable to the mapped path. **Example Docker Compose configuration:** ```yaml connector-service: image: pdftoolsag/connector-service:${IMAGE_VERSION} volumes: - ./Connections.xml:/etc/connsrv/Connections.xml environment: - IMPORT_CONNECTIONS=/etc/connsrv/Connections.xml ``` This imports and applies the `Connections.xml` configuration to the Connector Service on startup. --- ## Set up the service in your Docker container Use the Conversion Service either with Docker Compose or using your custom Docker configuration. - [Docker Compose configuration](#docker-compose-configuration) - [Custom Docker configuration](#custom-docker-configuration) ## Prerequisite Install Docker to enable use of the Conversion Service with both the Docker Compose or with your custom configuration. ## Docker Compose configuration Docker Compose lets you define and manage multi-container applications using a YAML file. This section illustrates the use of the Docker Compose with the Conversion Service. Using the Docker Compose with multiple interconnected services, specifically the Connector Service, Conversion Service, and Configuration Updater is recommended. The Docker Compose encapsulates the configuration of each service, its dependencies, and networking requirements within the `docker-compose.yaml` file. Docker Compose provides orchestration capabilities, automating the startup, shutdown, and scaling of containers, which is helpful for maintaining the integrity and availability of the Conversion Service system managed through Docker. ### Configure containers using Docker Compose The following code block includes an example of the `docker-compose.yaml` file you can copy and use. Specific details are explained in code comments: ```yaml volumes: vol-connector-srv: {} vol-conversion-srv: {} services: connector-service: # Connector Service image: # - Enables Watched Folders by monitoring a specified directory for incoming files. # - Enables REST Input connectors, both Plain HTTP and JSON. image: pdftoolsag/connector-service:${IMAGE_VERSION} ports: # Expose port 13034 for external communication. - "13034:13034" volumes: # Mount the host directory specified by `BASE_HOST_WATCHED_FOLDER` to /app/watched-folders/ # within the container used for Watched Folders. - ${BASE_HOST_WATCHED_FOLDER}:/app/watched-folders/ # Utilizes vol-connector-srv for configuration files. - vol-connector-srv:/app/config depends_on: # Dependent on configuration-updater. The service starts # only after the update was completed successfully. configuration-updater: condition: service_completed_successfully conversion-service: # Conversion Service image - Converts files to PDF format. image: pdftoolsag/conversion-service:${IMAGE_VERSION} volumes: # Utilizes vol-conversion-srv for configuration files. - vol-conversion-srv:/var/www/convsrv/bin/config environment: # To activate the license, pass the value of the license key. LICENSEKEY: ${LICENSE_KEY_VALUE} # Pass the URL of the Licensing Gateway Service endpoint LICENSINGSERVICE: http://license-gateway:9999 ports: # Exposes port 13033 for external communication. - "13033:13033" depends_on: # Dependent on configuration-updater. The service starts only after the update was completed successfully. configuration-updater: condition: service_completed_successfully # Dependent on license-gateway. The service starts only after license-gateway healthcheck pass. license-gateway: condition: service_healthy configuration-updater: # Configuration Updater - Updates configuration files for both connector-service and conversion-service. image: pdftoolsag/configuration-updater:${IMAGE_VERSION} volumes: # Utilizes vol-conversion-srv for updating Conversion Service configurations. - vol-conversion-srv:/app/conversion-config # Utilizes vol-connector-srv for updating Connector Service configurations. - vol-connector-srv:/app/connector-config license-gateway: image: pdftoolsag/license-gateway:${LICENSE_IMAGE_VERSION} ports: - "9999:9999" environment: - LICENSE_KEYS=${LICENSE_KEY_VALUE} healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9999/healthz/ready"] interval: 5s timeout: 3s retries: 3 ``` :::note[Page credit-based licensing with License Gateway Service] The `license-gateway` service and the `LICENSINGSERVICE` environment variable are only required when using a page credit license. If you are using a non-containerized version of the License Gateway Service (LGS), set `LICENSINGSERVICE` to the appropriate endpoint where LGS is accessible. The default port is 9999. Links to the topics mentioned in the previous code sample: - [Watched Folders](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder) - REST input connectors: - [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http) - [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-json) ### Run Docker Compose To run Docker Compose: 1. Save both `docker-compose.yaml` and `.env` file in the same directory. 1. Update the `.env` file to define three environment variables: - `BASE_HOST_WATCHED_FOLDER`: Path to the directory on the host machine watched by the Connector Service. - `LICENSE_KEY_VALUE`: Valid license key for the Conversion Service. - `IMAGE_VERSION`: The Conversion Service version number. For example: `6.0.0`, `6.0`, `6` - `LICENSE_IMAGE_VERSION`: The License Gateway Service version number. 1. Open the terminal and navigate to the directory where the `docker-compose.yaml` and `.env` files were saved. 1. Run Docker Compose: ```bash docker compose --env-file docker-compose.env up -d ``` ## Custom Docker configuration You configure the service in your Docker container at startup by passing [host address](#service-host-address), and [license key](#manage-license-keys) as environment variables. You can also set up a [proxy](#proxy) or a [load balancer](#load-balancer) as required. ### Service host address The port exposed by the container is `13033`. When running the container, the port must be published, which defines the address of the container's [REST service](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api) as: `http[s]://‹hostname›:‹port›/conversion/v1.0/rest`. This is the endpoint URL used by clients such as the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client). You should map the exposed port to the same port of the host machine: `http[s]://localhost:13033/conversion/v1.0/rest`. ### HTTPS By default, the service endpoint uses HTTP. Activating HTTPS disables support for HTTP to prevent clients from accidentally sending sensitive information over HTTP. You need to set `service__serviceEndpoint` to an URL with the format https://localhost:13033/conversion/v1.0/rest to activate HTTPS. When activating HTTPS, a valid host certificate is required. The certificate must be provided as PKCS\#12 file (`.pfx` or `.p12`), which includes the certificate's private key and issuer certificates. You specify the certificate path in `service__certificate__path`. If the private key is password protected, the password can be configured using `service__certificate__password`. ```bash docker run -dp 13033:13033 \ -e service__serviceEndpoint=https://localhost:13033/conversion/v1.0/rest \ --secret source=service_certificate,target=service_certificate \ -e service__certificate__path=/run/secrets/service_certificate \ pdftoolsag/conversion-service ``` ### Manage license keys 1. To activate the Conversion Service license, pass the license key using one of the following environment variables: 1. `LICENSEKEY`: The value of the parameter is the license key. ```bash docker run -dp 13033:13033 \ -e LICENSEKEY=4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \ pdftoolsag/conversion-service ``` 1. `LICENSEKEY_FILE`: The value of the parameter value is a path to a text file that contains the license key. ```bash docker run -dp 13033:13033 \ --secret source=service_licensekey,target=service_licensekey \ -e LICENSEKEY_FILE=/run/secrets/service_licensekey \ pdftoolsag/conversion-service ``` 1. Pass the LGS endpoint URL using the `LICENSINGSERVICE` parameter. The value is the URL of the LGS. ```bash docker run -dp 13033:13033 \ -e LICENSEKEY=4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \ -e LICENSINGSERVICE=http://:9999 \ pdftoolsag/conversion-service ``` :::info[Update or delete the license key] - To update the license key, remove the current Docker container where the Conversion Service is installed and start a new one. Then add and activate the license key as described in [Manage license keys](#manage-license-keys). - To delete the license key, remove the Docker container where you installed the Conversion Service. ### Proxy If you want to set a proxy, use the `HTTP_PROXY` environment variable. The proxy is used for both `http` and `https`. ### Cross-Origin Requests (CORS) You can restrict cross-origin requests to a set of allowed origins. Use the `CORS_ORIGINS` environment variable. The value is a comma-separated list of URLs. A wildcard `*` can be used to allow all origins or all subdomains of a specific domain. All parts of the URL must match, i.e. the scheme, host and port. The URLs must not specify a path, i.e. invalid URL: `https://www.example.com/`. **Examples:** - Allow all origins (default): `CORS_ORIGINS=*` - Allow single origin: `CORS_ORIGINS=https://www.example.com` - Allow multiple domains: `CORS_ORIGINS=https://www.example.com, https://www.domain.com` - Allow all subdomains: `CORS_ORIGINS=https://*.example.com` - Allow single domain and port: `CORS_ORIGINS=https://www.example.com:5000` ### Use forwarded HTTP headers from WAF Set the `USE_FORWARDED_HEADERS` to `True` to activate the use of forwarded HTTP headers. The header `X-Forwarded-For` Contains the IP address of the client that initiated the request. ### Load balancer Load balancing is supported. In addition to configuring the load balancer, there are also requirements on the clients in order to ensure optimal operation. The Conversion Service does not share resources among the backend servers, so each job is processed exclusively by the backend server where it has been created. Therefore, it is important to use sticky sessions in the load balancer so that all requests for a job are forwarded to the correct backend server. #### Configure the load balancer The load balancer must be configured to use sticky sessions. For this, it is recommended to use a cookie that is set upon the first request. **Kubernetes example 1. Annotations for NGINX Ingress Controller** ``` nginx.ingress.kubernetes.io/affinity: "cookie" nginx.ingress.kubernetes.io/affinity-mode: "persistent" nginx.ingress.kubernetes.io/session-cookie-name: "JOBSESSION" nginx.ingress.kubernetes.io/session-cookie-max-age: 3600 ``` **Kubernetes example 2. Annotations for Traefik Ingress Controller** ``` traefik.ingress.kubernetes.io/affinity: "true" traefik.ingress.kubernetes.io/session-cookie-name: "JOBSESSION" ``` While the healthcheck could be implemented using the HTTP status codes of the responses, it is recommended to use the service status request of the REST API. This allows to detect issues quicker and more reliably. #### Requirements on clients It is important the clients support the load balancer's job session cookie. After creating a job, the cookie must be stored and sent with subsequent requests. You should use a dedicated cookie store for each job. This enables the load balancer to distribute the processing of multiple jobs to multiple backend servers. The shell and GUI clients distributed with the Windows version of the Conversion Service adhere to these rules. Therefore, they are suitable to test the load balancer configurations. :::caution[Converting Office Documents] The Conversion Service converts Word, Excel, and PowerPoint files to PDF by default using the Standard Converter. No additional configuration is required. For highest visual fidelity, see [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). To add custom fonts, see [Fonts in Docker](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#fonts-in-docker). --- ## Configure emails Learn how to configure the displayed output of emails converted by the Conversion Service. Choose the time format displayed in the header of the converted email document, configure whether to include external images, change the page size, page margin, and a default language. Email processing settings are determined by the profile. You configure email settings using the Configurator. ## Configure email processing To configure email processing for a profile, go to the Profile settings and find the **Email Settings** section. For Archive as PDF/A-2 workflows, you can choose to use the email subject as the filename of the converted email file by enabling **Use Subject As Filename**. You can choose how the time is displayed in the header of the converted email: - **Zone**: Time zone to be displayed in the output document. You can choose to display the time as: - **Original**: The time zone used by the original email. - **Local**: The time zone of the server. - **UTC**: Universal time (Coordinated). - **Format value**: Displays the time in the output document. The Conversion Service uses standard .NET notation for date format strings. For more information on date format strings in .NET, see [Standard date and time format strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings). **In this format, do not use or enter double quotes.** - Empty value: Full date/time pattern with offset. This is especially useful when using the *Original* time zone setting. - `F`: Full date/time pattern (long time) without any offset. This is especially useful when using the *Local* time zone setting. - `dd.MM.yyyy HH:mm:ss (zzz)`: Default value in previous versions of the Conversion Service. ## Configure output file appearance To configure the appearance of the converted email files: 1. In the Conversion Service Configurator, navigate to the Profile settings 1. Scroll to the **Document Settings** section. Emails don't include any page size information. As a result, you can adjust the page size dynamically using this configuration. - **Default Page Size**: The default page size for documents that don't explicitly specify the page size. - **A4**: A4 sheets have a width of 210 mm and a length of 297 mm. - **Letter**: US letter paper has a width of 215.9 mm with a length of 279.4 mm. - **Default Page Margin**: The default page margin is 20 mm. - **Default Language**: The language used for dynamically generated content such as the date format, email header field names, and PDF collection table header. - **Include external images**: Include external images from HTML and email files. If you disable this option, the URLs pointing to external resources are replaced with a placeholder. :::tip[Built-in documentation] For more details, you can refer to the built-in documentation within the Conversion Service Configurator. To access built-in documentation, click the icon next to the **Email Settings** or **Document Settings** configuration section header. --- ## Configure job and document options Job and document options let you provide document or job-specific data to be added during the conversion process. Job and document options are defined at profile level and are specific to each workflow. Options are available for the [Convert to PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion), [Prepare Invoice PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/invoice), [Create Dossier PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier), [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2), [Archive as PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3), and [Archive as PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1) workflows. The default values taken for a profile are determined in the [profile settings](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). You can override the values for these settings using the job and document options during runtime. For example, you can use the metadata document option (`META.AUTHOR`) to indicate the author of a document. If you enter the name "Jo Smith" in the **Author** field of the profile settings, all documents processed using that profile will have "Jo Smith" as the author. If you pass the value "Jo Smith" using the `META.AUTHOR` document option during runtime, only documents processed as part of that specific job will have the author "Jo Smith". As another example, let's say that multiple documents have different passwords. You can specify the password by document using document options. Alternatively, using the job options instead of the document options, you can specify all passwords and then the Conversion Service tries each password on each document. **tip: Not all configuration settings can be controlled by job and document options. If there is no job or document option available for the behavior you require, you need to create a separate profile for this configuration.** ## Customize job and document option names Some job and document options are predetermined (e.g. `META.TITLE` and other document [metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)). Other job or document options can be customized to use your own specific string. The Configurator lets you change the name of specific job and document options. In the Configurator, an icon appears to the right of the option to indicate the job or document options you can customize: - **Inactive Gear** icon: indicates that the name of the job or document option is fixed and cannot be changed. - **Active Gear** icon: indicates that a custom name can be set up for this job or document option. Click the icon to enter a custom name for the job or document option or edit an existing name. You can use the custom name to pass a specific value when you perform a workflow using that profile. --- ## Conversion Service on OpenShift Learn how to configure and deploy the Conversion Service on OpenShift. ## Prerequisites - You have created an operational OpenShift cluster. - You have a valid license key for the Conversion Service. - Optional: You have a Windows Server machine with configured Microsoft Office for document conversion. This configuration is recommended for the best results when converting Microsoft Office documents. ## Configure Conversion Service on OpenShift **Steps to implement the Conversion Service on OpenShift:** 1. [Use configuration file](#use-configuration-file) 1. [Deploy on OpenShift](#deploy-on-openshift) 1. [Import profiles](#import-profiles) 1. [Enable Microsoft Office document conversion](#enable-microsoft-office-document-conversion) 1. [HTTPS setup](#https-setup) ### Use configuration file Deploy the Conversion Service with multiple replicas, a single shared volume for temporary files, and sticky sessions using the `conversion-service.yaml` configuration file below. Copy the code or change it to use it in your deployment: ```yaml ############################################################################## # DEPLOYMENT: 2 replicas ############################################################################## apiVersion: apps/v1 kind: Deployment metadata: name: conversion-service spec: replicas: 2 selector: matchLabels: app: conversion-service template: metadata: labels: app: conversion-service spec: containers: - name: conversion-service image: pdftoolsag/conversion-service:IMAGE_VERSION ports: - containerPort: 13033 env: - name: LICENSEKEY value: "LICENSE_KEY_VALUE" volumeMounts: - name: convsrv-temp mountPath: "/tmp/convsrv" # Single writable volume for all temp files volumes: - name: convsrv-temp emptyDir: {} # One volume for all temp files --- ############################################################################## # SERVICE: Exposes the pods internally on port 13033. ############################################################################## apiVersion: v1 kind: Service metadata: name: conversion-service spec: selector: app: conversion-service ports: - protocol: TCP port: 13033 targetPort: 13033 --- ############################################################################## # ROUTE: Cookie-based sticky sessions ############################################################################## apiVersion: route.openshift.io/v1 kind: Route metadata: name: conversion-service annotations: haproxy.router.openshift.io/affinity: "cookie" haproxy.router.openshift.io/session-cookie-name: "conversion-service-session" spec: to: kind: Service name: conversion-service port: targetPort: 13033 ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number. For example: `6.0.0`, `6.0`, `6` - `LICENSE_KEY_VALUE`: Pass the license key value. **note: - `haproxy.router.openshift.io/affinity: "cookie"`: Instructs the OpenShift HAProxy router to enable session affinity using cookies.** - `haproxy.router.openshift.io/session-cookie-name: "conversion-service-session"`: Sets the name of the cookie that the router uses to maintain session affinity. These annotations ensure that all requests for a single conversion job are directed to the same pod (especially when using the [Advanced API](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/advanced-api)), preventing issues with stateful operations. ### Deploy on OpenShift 1. Create a new project: ```shell oc new-project PROJECT_NAME ``` Replace `PROJECT_NAME` with the name of the project. 1. Apply the `conversion-service.yaml` file: ```shell oc apply -f conversion-service.yaml ``` 1. Verify deployment: ```powershell oc get pods ``` 1. Confirm that the Conversion Service and route are created: ```shell oc get svc oc get route ``` 1. Test the Conversion Service endpoint. If your route hostname is `conversion-service-PROJECT_NAME.apps-crc.testing`, run: ```powershell curl http://conversion-service-PROJECT_NAME.apps-crc.testing/conversion/v1.0/rest ``` Replace `PROJECT_NAME` with the name of your project. ### Enable Microsoft Office document conversion To enable Microsoft Office document conversion for the Conversion Service on OpenShift, you have two possible options: 1. [Recommended: Windows Server for Microsoft Office conversion](#recommended-windows-server-for-microsoft-office-conversion) 2. [Office for the web service API](#office-for-the-web-service-api) #### Recommended: Windows Server for Microsoft Office conversion We recommend installing a dedicated Windows Server with Microsoft Office for the highest-fidelity Office conversion. 1. Deploy a Windows Server: - Install Microsoft Office according to your licensing requirements. - Use dedicated hardware or a virtual machine within your infrastructure. 1. Enable Office conversion in your Conversion Service profile. For more details, review [Configure Microsoft Office file conversion](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server#configure-microsoft-office-file-conversion). 1. If you intend to secure the traffic with HTTPS, install trusted certificates on Windows Server and OpenShift. #### Office for the web service API Using Office for the web service API has limitations—including reduced support for embedded fonts and potential localization or formatting issues. **caution: We do not recommend the Office for the web service API for critical or large-scale use cases. If you need a large-scale conversion of files, review [Recommended: Windows Server for Microsoft Office conversion](#recommended-windows-server-for-microsoft-office-conversion) instead.** The following steps do not encompass specific actions but provide an overall direction to implement Office for the web service conversion with OpenShift: 1. Enable Office Conversion in your profile through the `csconfig` tool or by editing your existing profile. Office conversion is on by default, but ensure you set `OfficeWebService` in the processing steps of the Conversion Service. 2. Consent to application permissions and initialize token cache: - Review Docker-specific tabs in [Install and configure local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#install-and-configure-local-microsoft-office-installation) documentation. Then, run `csconfig office webinit` inside the container to handle the OAuth. - In OpenShift, you can mount a persistent volume (for example, a PVC) at `/etc/convsrv` so the token cache can be stored under `/etc/convsrv/TokenCaches`. 3. Set the following environment variables in your `conversion-service.yaml` file: - `SERVICE__OFFICE__TYPE=OfficeWebService` - `SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com` - Mount the volume with the token cache to `/etc/convsrv` in the container. ### Import profiles Profiles allow you to customize conversion behavior, such as image compression, PDF/A compliance, or other specialized settings. In an OpenShift environment, you can import profiles using a ConfigMap: 1. ​Export a Conversion Service profile. Review [Configure and export a profile](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker#configure-and-export-a-profile) section of the Docker getting started guide. 1. Create a ConfigMap from the exported profile: ```shell oc create configmap conversion-profile --from-file=ProfileExport-EXPORTED_PROFILE_VERSION.export ``` Replace the `EXPORTED_PROFILE_VERSION`: Use the version number of your exported profile. For example: `5.7.2` 1. Update your `conversion-service.yaml` to mount the ConfigMap as a volume and set the environment variable `IMPORT_PROFILES` to the file's path. For example: ```shell ############################################################################## # DEPLOYMENT ############################################################################## apiVersion: apps/v1 kind: Deployment metadata: name: conversion-service spec: replicas: 2 selector: matchLabels: app: conversion-service template: metadata: labels: app: conversion-service spec: containers: - name: conversion-service image: pdftoolsag/conversion-service:IMAGE_VERSION ports: - containerPort: 13033 env: - name: LICENSEKEY value: "LICENSE_KEY_VALUE" - name: IMPORT_PROFILES value: "/etc/convsrv/ProfileExport-EXPORTED_PROFILE_VERSION.export" - name: WINDOWS_SERVICE_ENDPOINT value: "http://WINDOWS_SERVER_IP_ADDRESS:13033/conversion/v1.0/rest" volumeMounts: - name: convsrv-temp mountPath: "/tmp/convsrv" - name: convsrv-profile mountPath: "/etc/convsrv" readOnly: true volumes: - name: convsrv-temp emptyDir: {} - name: convsrv-profile configMap: name: conversion-profile --- ############################################################################## # SERVICE ############################################################################## apiVersion: v1 kind: Service metadata: name: conversion-service spec: selector: app: conversion-service ports: - protocol: TCP port: 13033 targetPort: 13033 --- ############################################################################## # ROUTE ############################################################################## apiVersion: route.openshift.io/v1 kind: Route metadata: name: conversion-service annotations: haproxy.router.openshift.io/affinity: "cookie" haproxy.router.openshift.io/session-cookie-name: "conversion-service-session" spec: to: kind: Service name: conversion-service port: targetPort: 13033 ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number. For example: `6.0.0`, `6.0`, `6` - `LICENSE_KEY_VALUE`: Pass the license key value. - `EXPORTED_PROFILE_VERSION`: Use the version number of your exported profile. For example: `5.7.2` - `WINDOWS_SERVER_IP_ADDRESS`: Pass the IP address of your Windows Server. If you don't want to use Microsoft Office Conversion, you can remove the `WINDOWS_SERVICE_ENDPOINT` environment variable. 1. Optional: If you configured **Office for the web service API** instead of the recommended **Windows Server for Microsoft Office conversion**: - Remove the `WINDOWS_SERVICE_ENDPOINT` variable from the `conversion-service.yaml` file. - Follow the instructions described in [Office for the web service API](#office-for-the-web-service-api) section. 1. Deploy or update ```shell oc apply -f conversion-service.yaml ``` The service starts with the imported profile. ### HTTPS setup Ensure the Conversion Service is secured with HTTPS in production environments. In OpenShift, you can configure TLS protocol termination at the route level. 1. Create or provide a valid TLS certificate. 1. To enable TLS in the route configuration, add a `tls` section: ```yaml apiVersion: route.openshift.io/v1 kind: Route metadata: name: conversion-service spec: to: kind: Service name: conversion-service port: targetPort: 13033 tls: termination: edge key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- certificate: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- caCertificate: | ... ``` ## Optional configurations The following sections offer ideas for alternative configurations. ### Configure HTTPS directly in the container This section presents an alternative to the recommended [HTTPS setup](#https-setup). If you prefer to configure HTTPS inside the container itself rather than at the OpenShift route layer, review [Docker HTTPS configuration guide](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container#https). ### NGINX for complex setups You can integrate an NGINX reverse proxy for more advanced routing or load balancing rules (for example, custom URL paths, additional security headers, or advanced caching). This can be done by: - Running NGINX as a sidecar container in the same pod as the Conversion Service. - Setting up NGINX in a separate deployment and routing traffic to your Conversion Service through the NGINX layer. --- ## Configure Conversion Service plugins Plugins are non-standard components used for extending the Conversion Service with custom workflows. ## Manage plugins Depending on your installation, plugins are managed differently. **Windows:** You can install plugins using the Plugins tab of the Conversion Service Configurator GUI. The tab is only displayed if the corresponding license feature is active. All installed plugins are listed here. To install a new plugin, click **Install Plugin** and choose the ZIP file containing it. To update or delete a plugin, click on the respective icon. **info: You must restart the service for any changes in plugins to take effect.** **Docker:** To run a Conversion Service with a plugin, a custom image must be created. The `csconfig` command can be used in the `Dockerfile` to install the plugin: **Example Dockerfile for installing a plugin with the Conversion Service:** ``` FROM pdftoolsag/conversion-service:IMAGE_VERSION USER root COPY PLUGIN_FILE . RUN bin/csconfig plugins install PLUGIN_FILE \ && rm PLUGIN_FILE COPY PROFILE_EXPORT_FILE . RUN bin/csconfig profiles import -r PROFILE_EXPORT_FILE \ && rm PROFILE_EXPORT_FILE USER convsrv ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). - `PLUGIN_FILE`: The plugin archive filename (for example, `Plugin-1.2.0.zip`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). Each plugin version is designed for a specific version of the Conversion Service. So when upgrading the Conversion Service, all plugins must be upgraded as well. Unless the plugins are updated, the service is not operational. --- ## Configure profiles in Docker For Docker container installations, you need to [create a profile](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) using a Windows installation, [export it](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles#exporting-profiles), and import it into your container. The version of the Conversion Service installed on Windows and the version of the container image **must match**. If you need to update to a new version, update the Windows service first as this automatically updates the configured profiles if necessary. Make sure that all configuration values are valid in your Docker environment, i.e. URLs to services and paths to configuration files. **info: Alternatively, configure profiles using the web application **Configurator Web**. It is in the beta version and doesn't support all the Windows Conversion Service Configurator capabilities. You can find more information in the [Configure profiles using Configurator Web](#configure-profiles-using-configurator-web) section.** ## Set a profile when starting the Docker container The exported profile file (for example, `ProfileExport-6.11.0.export`, where the version matches the Conversion Service that exported it) must be mounted into the container. Set the `IMPORT_PROFILES` environment variable to the file path inside the container. ## Import profiles only This profile configuration imports the exported profile file only, which is typically sufficient. Bind the exported profile file to the container and set the environment variable `IMPORT_PROFILES` to activate the profile import: ``` docker run -dp 13033:13033 --network conversion-service \ --mount "type=bind,src=HOST_PROFILE_DIR\PROFILE_EXPORT_FILE,\ dst=/etc/convsrv/ProfileExport.export,readonly" \ -e IMPORT_PROFILES=/etc/convsrv/ProfileExport.export \ -e LICENSEKEY=LICENSE_KEY_VALUE \ pdftoolsag/conversion-service:IMAGE_VERSION ``` Replace the following: - `HOST_PROFILE_DIR`: The directory on the host machine that contains the exported profile (for example, `C:\Users\john-doe\Desktop`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). When importing profiles of a workflow, you also import the **Workflow state**, whether the workflow is activated or deactivated. ## Import profiles and further configuration files This more advanced profile configuration is required for profiles that contain references to files, e.g. SSL client certificates for connections to external servers. 1. When configuring the profiles, use the base path `/etc/convsrv` for all referenced files. 2. Create a directory `configuration` where all configuration files can be written to. Later these files will be copied to a volume and mapped to `/etc/convsrv` in the container. 3. Copy the exported profile file and all referenced files to the directory `configuration`. 4. Create a volume named after the Conversion Service version (for example, `convsrv-etc-6.11.0`) containing all configuration files from `configuration`: ``` docker volume create --name VOLUME_NAME docker run --rm \ --mount "type=bind,src=HOST_CONFIG_DIR,dst=/source" \ --mount "type=volume,src=VOLUME_NAME,dst=/etc/convsrv" \ alpine \ ash -c "cp /source/* /etc/convsrv/" ``` Replace the following: - `VOLUME_NAME`: A Docker volume name that includes the Conversion Service version (for example, `convsrv-etc-6.11.0`). - `HOST_CONFIG_DIR`: The directory on the host machine that contains the exported profile and any referenced files (for example, `C:\path\to\configuration`). 5. The folder `configuration` is not required anymore and can be deleted. 6. Run the image. Mount the volume and set the environment variable `IMPORT_PROFILES` to activate the profile import: ``` docker run -dp 13033:13033 --network conversion-service \ --mount "type=volume,src=VOLUME_NAME,dst=/etc/convsrv,readonly" \ -e IMPORT_PROFILES=/etc/convsrv/PROFILE_EXPORT_FILE \ -e LICENSEKEY=LICENSE_KEY_VALUE \ pdftoolsag/conversion-service:IMAGE_VERSION ``` Replace the following: - `VOLUME_NAME`: The Docker volume name created in the previous step (for example, `convsrv-etc-6.11.0`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). ## Import profiles using Docker Compose To import an exported profile in a Docker Compose setup, mount the export file as a volume and set the `IMPORT_PROFILES` environment variable: ```yaml services: conversion-service: image: pdftoolsag/conversion-service:IMAGE_VERSION environment: LICENSEKEY: LICENSE_KEY_VALUE IMPORT_PROFILES: /etc/convsrv/ProfileExport.export ports: - "13033:13033" volumes: - ./PROFILE_EXPORT_FILE:/etc/convsrv/ProfileExport.export ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `PROFILE_EXPORT_FILE`: The filename of the exported profile on your host machine (for example, `ProfileExport-6.11.0.export`). For the full Docker Compose configuration reference, refer to [Configure containers using Docker Compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container#configure-containers-using-docker-compose). ## Configure profiles using Configurator Web Set up the Conversion Service profiles and workflows in Docker. Use the Configurator Web, a cross-platform application that removes the need to manage configuration on Windows machines. :::info[Configurator Web beta] The Configurator Web is still in beta and does not support all the capabilities of the Conversion Service Configurator on Windows. Use the following code in your Docker compose YAML configuration file: ```yaml volumes: vol-conversion-srv: {} services: conversion-service: # Conversion Service image. Converts files to PDF format. image: pdftoolsag/conversion-service:IMAGE_VERSION volumes: # Utilizes vol-conversion-srv for configuration files. - vol-conversion-srv:/var/www/convsrv/bin/config environment: # To activate the license, pass the value of the license key. LICENSEKEY: LICENSE_KEY_VALUE # Pass the URL of the Licensing Gateway Service endpoint LICENSINGSERVICE: LICENSING_SERVICE_ENDPOINT ports: # Exposes port 13033 for external communication. - "13033:13033" configurator-web: # Configurator Web image. Configures profiles and workflows. image: pdftoolsag/configurator-web:IMAGE_VERSION volumes: # Utilizes vol-conversion-srv for configuration files. - vol-conversion-srv:/app/conversion-config ports: # Exposes port 13035 for external communication. - "13035:13035" ``` Replace the following: - `IMAGE_VERSION`: Specify the image version you want to use. Note that this variable is included twice in the code snippet above. Example value: `6.0.0`. - `LICENSE_KEY_VALUE`: Pass the license key value. - `LICENSING_SERVICE_ENDPOINT`: Pass the URL of the Licensing Gateway Service endpoint. The Configurator Web is available at `http://localhost:13035` by default. The example Docker compose file demonstrates how to run the Conversion Service and Configurator Web simultaneously with a shared configuration file. **tip: Once you have configured the profiles in the Configurator Web application:** 1. Click **Save**. 1. Restart the Conversion Service container. --- ## Configure profiles A profile is a structured, workflow-specific set of configuration settings. Each [workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/) can have an arbitrary number of profiles, which you can select when running the service. Profiles are managed using the Conversion Service Configurator in the Workflows & Profiles tab. The Configurator is added to the Windows start menu during installation. :::info[For Docker version only] If you are using the Conversion Service in a Docker container, you need to **create a profile using a Windows installation** before exporting and importing it into the Docker container. See **[Configuring profiles in Docker containers](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker)**. ## Adding and editing profiles In the Workflows & Profiles tab, click **Add** to add and configure a new profile. To edit an existing profile, simply click on it. To copy an existing profile, click the Copy icon. ## Importing profiles Click **Import Profiles** in the top-right menu to import profiles from a profile configuration file. If a profile with the same name is selected in the same workflow as an already existing profile, a dialog with the following options appears: - **Deselect duplicates**: Select this option if you only want to add, but not replace any existing profiles. - **Replace originals with imported profiles**: Select this option if you want to replace the existing profiles. - **Keep originals and imported profiles**: Select this option if you want to keep both, the existing and the imported profiles. When importing profiles of a workflow, the following workflow properties are also imported: - **Workflow state**: Whether the workflow is activated or deactivated. - **Default workflow**: If the default workflow is exported, it is set as default workflow on import. ## Exporting profiles Click **Export Profiles** in the top-right menu to export one or more profiles to a profile configuration file. - **Name (required)**: Enter the desired name for the profile. - **Default**: Check this box to set the current profile as the default profile for the given workflow. - **Processing Steps**: Enable or disable optional processing steps. Corresponding options are displayed accordingly. - **Options**: Set options for individual processing steps. A summary for each option is documented with tooltips. For a detailed explanation of the options, click on the title of the corresponding section to open the documentation panel. **caution: You must restart the service for the configuration changes to take effect.** When you add or edit profiles, the Configurator detects changes and displays an unobtrusive notification. For your convenience, your changes are kept in memory, until you click **Save & Restart Service** in the notification. **tip: Name the exported profile file using the pattern `ProfileExport-VERSION.export`, where `VERSION` is the Conversion Service version number (for example, `ProfileExport-6.11.0.export`).** --- ## Configure digital signature Learn how to set up digital signatures in the Conversion Service using various online and offline signature providers. **tip: For theoretical information about digital signatures, review [Digital signature basics](https://www.pdf-tools.com/docs/knowledge/digital-signature-basics/).** ## Enable sign option in a profile To add a digital signature to a profile: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Choose a workflow that supports digital signatures. You can add digital signatures to PDF and PDF/A files in the following workflows: - [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) - [Archive as PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3) - [Prepare Invoice PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/invoice) - [Sign PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/sign) :::caution The Sign PDF workflow doesn't remove previous signatures. Other workflows can remove signatures from documents while adding a new signature. ::: 1. Click the pen icon to edit the profile configuration. 1. Enable the **Digital Signature** toggle. Note that the toggle is always enabled in the Sign PDF workflow by default. ## Digital signature configuration When you enable the Digital Signature option in a profile, the Configurator displays an additional configuration section that allows you to add different signature types for that specific profile. To add a new signature: 1. Click **Add Item** to add a new signature. 1. Choose one of the available signature providers with various signature types: - **GlobalSign**: Use a Cloud-based Digital Signing Service. - **PKCS#11**: Create a signature using a signing certificate from a PKCS#11 device, such as a hardware security module (HSM). - **Swisscom Signing Service**: Use the Swisscom Signing Service to create a signature. - **Windows**: Create a signature using a signing certificate from the Windows Certificate store. 1. Configure the options for the signature type: - [Configure GlobalSign signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-globalsign) - [Configure PKCS#11 signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-pkcs11) - [Configure Swisscom Signing Service signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-swisscom) - [Configure Windows signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-builtin) **note: With the Conversion Service, you can't set and position signature visual representation.** The added digital signature is only visible in the signature panel in PDF readers that support viewing digital signatures. However, you can configure the visual appearance of digital signatures with the Pdftools SDK. For more information, review [Create a signature visual appearance](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/signature-appearance/) in the Pdftools SDK documentation. --- ## Cryptographic providers With the Conversion Service, you can create digital signatures in PDF and PDF/A files. You can choose from local and online cryptographic providers to support your legal and regulatory requirements. The cryptographic provider manages certificates and the associated private keys and implements cryptographic algorithms. ## Before you start Before you apply a digital signature to a document, configure a cryptographic provider. The cryptographic provider impacts the legal effect of your digital signatures and often depends on your local legal and regulatory requirements. **tip: If you need clarification on your local legal and regulatory requirements about the legal effect of a digital signature, contact your local certificate authority (CA) for guidance.** ### Preparation before creating a digital signature The following steps can help you identify which type of digital signature you need before you implement it in the Conversion Service: 1. Identify whether you require: - Simple electronic signature - Advanced electronic signature (AdES) - Qualified electronic signature - Timestamp signature An advanced signature is sufficient for automated processes, like applying signatures on multiple documents at once. 2. Determine signature lifecycle regulations. - Is a timestamp required to prove that the signature existed at a specific date and time? - Is it necessary to embed validation information to allow the signature validation after the signature is generated? - Is a specific signature encoding required? These regulatory requirements define the signature level that you must use. 3. Acquire a corresponding certificate from a certificate authority. Use either: - A hardware security module (HSM). - An online signing service. - Soft certificates. - Other hardware, such as USB tokens or smart cards. 4. Set up and configure the certificate cryptographic provider. - If the certificate is provided by hardware, install the required middleware (driver). - If the certificate is a soft certificate, import it into the cryptographic provider's certificate store. 5. Optional: Acquire access to timestamp authority (TSA), preferably from a certificate authority of your signing certificate. 6. Optional: Sign documents in PDF/A format. Using files conforming to the PDF/A standard as an input has several benefits: - PDF/A format ensures that the visual appearance of files can be reproduced in any environment. - PDF/A conformance is required if the file is to be archived. - Signatures can break when converting signed files to PDF/A. Convert files to PDF/A before signing them. ### Supported digital signature types Available signature providers in the Conversion Service are the following: - [GlobalSign](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-globalsign) (Online Service) - PADES-B-LT/LTA - [PKCS#11](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-pkcs11) (Hardware Module) - PADES-B-T - PADES-B-LT/LTA - [Swisscom](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-swisscom) (Online Service) - PADES-B-T - PADES-B-LT/LTA - On-Demand - [Windows](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/provider-builtin) (Soft certificate) - PADES-B-B - PADES-B-T - PADES-B-LT/LTA ## Types of cryptographic providers The following sections explain the most common types of cryptographic providers. As stated previously, configure a cryptographic provider before applying a digital signature to a document. ### Online signing services Online signing services are cloud-based cryptographic providers that enable their customers to sign documents and provide them with time-stamps. These services provide a convenient alternative to storing certificates and private keys. The Conversion Service supports the following online certificate providers: - **Swisscom All-in** Signing Service - **GlobalSign** Digital Signing Service **note: The GlobalSign and Swisscom cryptographic providers have their own TSA that lets you generate trusted time-stamp information.** ### Soft certificate Soft certificates are files which contain certificates. These files are typically in **PKCS#12** archive file format with `.pfx` or `.p12` file extensions. Soft certificate files contain the signing certificate, as well as the private key and trust chain (issuer certificates). **info: In the Conversion Service, you cannot use soft certificate files directly. However, you can import them into the certificate store of a cryptographic provider.** The recommended way of using soft certificates is to import them into a store that offers a PKCS#11 interface and use the **PKCS#11 provider**. **info: On Windows, if no PKCS#11 provider is available, you can import the soft certificates into the **Windows certificate store**, which you can then use as a cryptographic provider. Note that the Windows and PKCS#11 cryptographic providers can require a third-party TSA to be configured.** ### Hardware Security Module Hardware Security Modules (HSMs) offer a good **PKCS#11** support. For more information and installation instructions, see the separate document [TechNotePKCS11.pdf](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf). You might use other hardware, such as USB tokens or smart cards. ## General settings of cryptographic providers The following sections explain common settings of cryptographic providers in the Conversion Service. ### Trust store Trust store is a repository that holds digital certificates issued by the certificate authority (CA). When the Conversion Service connects to a remote service (Swisscom, GlobalSign), the server certificate's trustworthiness has to be verified. The verification process requires a trust store, otherwise, verification always fails. The Windows certificate store for **Trusted Root Certification Authorities** is used. You can install the root certificate of a private CA manually on a computer by using the 'CertMgr' tool. The certificate store is only available if the user profile has been loaded. A server's certificate is considered trustworthy if it matches a certificate in the trust store or one of its issuer certificates. **note: Connections to untrusted servers are not established, as this could pose a security risk. Such attempts are treated as internal configuration errors and an error message like the following is logged:** *"Failed to connect to the signing service: Cannot create a session: certificate verify failed."* ### Proxy settings Some of the features of the Pdftools Conversion Service require access to a remote service. These features include: - Connecting to a [time-stamp authority (TSA)](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/timestamp-authority/) to retrieve a time-stamp - Connecting to an [online signing service](#online-signing-services) to access document signing functions - Connecting to a certificate authority to retrieve certificates and revocation information If your software runs in a secured environment, it can be necessary to configure a proxy server to route requests to these remote services. **note: The default value for the `Proxy` server URI property is `null`, meaning that no proxy is used. Otherwise, you have to set the proxy.** Set it in the `C:\Program Files\Pdftools\Conversion Service\bin\appsettings.json` manually. ### Signature level Signature level (marked as **Signature-level** in the Conversion Service Configurator) specify levels of security that a digital signature provides. #### PaDES-B-LT By default long-term validation (LTV) information is added to the output document. The PaDES-B-LT embeds revocation information such as online certificate status (OCSP) response and certificate revocation lists (CRL). Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. LTV (Long-Term Validation) **records the Certificate state at the time of signing**. To validate a certificate, the time and date the PDF file was signed need to be known. To make this undisputable, the signature has to be digitally timestamped. #### PaDES-B-LTA To obtain a higher security level of a signature, choose **PaDES-B-LTA** instead of PaDES-B-LT. PaDES-B-LTA adds an additional time-stamp signature to the document. Note that for PAdES-B-LTA signatures, enable the creation of Trusted Time-stamps in the corresponding account. --- ## Windows signature This cryptographic provider uses Windows infrastructure (such as Microsoft Windows certificate store) to access certificates and to supply cryptographic algorithms. :::tip[Supported signature standards] Windows cryptographic provider offers options to configure various digital signature types: - **PADES-B-B**: Basic digital signature type that requires no time-stamp authority (TSA) nor revocation information (CRL, OCSP). - **PADES-B-T**: Digital signature with a timestamp token. - **PADES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. **info: Note that the signing certificate must be available to the user, under which the service runs, and also in its session.** ## Configure Windows signature The following sections introduce [Configuration examples](#configuration-examples) and detailed descriptions of each configuration option in the [Identity settings](#identity-settings) section. ### Configuration examples This section includes screenshots from the Conversion Service Configurator with configuration details of each signature type provided by the Windows cryptographic provider. - **PaDES-B-B**: Basic digital signature type that requires no time-stamp authority (TSA) nor revocation information (CRL, OCSP). - **PaDES-B-T**: Digital signature with a timestamp token. - **PaDES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. --- ### Identity settings The following sections describe specific configuration options in the identity section of the digital signature configuration. #### Common Name The name of the signing certificate. This is the common name of the certificate subject with limited support for placeholders. #### Thumbprint The SHA-1 thumbprint (also called fingerprint) of the signing certificate, with limited support for placeholders, is required for certificate selection. **note: If this value is incorrect, the error message in the service log is:** *"Certificate not found in store."*. The thumbprint value must be a string of hexadecimal digits and its characters must be in the ranges `0-9`, `a-f`, `A-F`, and spaces. You can directly use the **Thumbprint** value displayed in the Windows certificate dialog. Examples: - `005572a2d0242a0121c8dee341463a63ae9cabdf` - `00 55 72 A2 D0 24 2A 01 21 C8 DE E3 41 46 3A 63 AE 9C AB DF` Supported placeholders: - `[custom:]` - A custom placeholder. #### TSA The URL of the trusted TSA from which you acquire a timestamp. **note: Applying a time stamp requires an online connection to the time server and you must configure firewall accordingly.** If a web proxy is used, ensure the following MIME types are supported: - `application/timestamp-query` - `application/timestamp-reply` #### Fallback TSA If the primary TSA is unavailable, this fallback URL is used to get the timestamp instead. #### Add Revocation Information Whether to add revocation information (OCSP, CRL) to the document time-stamp signature. For example, to make a signature with enabled Long Term Validation (LTV). #### Signature-level The signature level is a general setting for every signature provider. Review [Signature level](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#signature-level) for more information. --- ## GlobalSign Digital Signing Service Online signing services are cloud-based cryptographic providers that enable their customers to sign documents and provide them with time stamps. This cryptographic provider lets you access the GlobalSign Digital Signing Service (GlobalSign DSS). You can use the GlobalSign DSS to perform cryptographic functions such as signing a document. :::tip[Supported signature standards] GlobalSign cryptographic provider offers options to configure various digital signature types: - **PADES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. :::note[Prerequisite] This cryptographic provider implements the [GlobalSign Digital Signing Service](https://www.globalsign.com/en/document-signing) methods. This provider requires a GlobalSign DSS account. ## Configure GlobalSign Digital Signing Service The following sections introduce [Configuration example](#configuration-example) and provide detailed descriptions of each configuration option in the [Identity settings](#identity-settings), [Provider settings](#provider-settings), and [Endpoint settings](#endpoint-settings) sections. ### Configuration example - **PaDES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. --- ### Identity settings The following sections describe specific configuration options in the identity section of the digital signature configuration. #### Common Name The name of the signing certificate. This is the common name of the certificate subject with limited support for placeholders. #### Identity Parameter to create the signing certificate with limited support for placeholders. Accounts with static and dynamic identities are supported. - Account with a static identity: `{}` - Account with a dynamic identity: `{ "subject_dn": {"common_name": "John Doe"}}` - Supported placeholders: `[custom:]` #### Signature Level The signature level is a general setting for every signature provider. Review [Signature level](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#signature-level) for more information. --- ### Provider settings When you have a defined endpoint, you can open a session by logging in with the API key and secret from your GlobalSign DSS account. #### API key Your GlobalSign DSS account credentials key parameter for the login request. #### API secret Your GlobalSign DSS account credentials secret parameter for the login request. --- ### Endpoint settings GlobalSign provides signing certificates and basic cryptographic signatures. When using this cryptographic provider, you need your GlobalSign account's SSL client certificate, private key, and password. #### SSL client certificate SSL client certificate in PKCS#12 Format (.p12 or .pfx). The file must contain the certificate, all trust chain certificates, and the private key. **note: The PKCS#12 file can be generated from the client certificate (`clientcert.crt`) and its private key (`privateKey.key`) using the following command:** `openssl pkcs12 -export -out certificate.p12 -inkey privateKey.key -in clientcert.crt` It is strongly recommended that the private key is protected using a password. This password must be configured below. #### Password Password to decrypt the private key of the SSL client certificate. #### Trust store/Private key [Trust store](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#trust-store) is a general settings among online signature providers. #### Address The service endpoint URL. --- ## PKCS#11 The PKCS#11 provider creates a session with a cryptographic device (for example HSM, USB token) to perform cryptographic operations. The cryptographic device often requires a driver module (middleware). Find more information about required drivers in the documentation of your cryptographic device. :::tip[Supported signature standards] PKCS#11 cryptographic provider offers options to configure various digital signature types: - **PADES-B-B**: Basic digital signature type that requires no time-stamp authority (TSA) nor revocation information (CRL, OCSP). - **PADES-B-T**: Digital signature with a timestamp token. - **PADES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. **note: The [PKCS#11 Tech Note](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf) provides detailed information about configuring a PKCS#11 device to work with the Pdftools Conversion Service.** ## Configure PKCS#11 Signing Service The following sections introduce [Configuration example](#configuration-examples) and provide detailed descriptions of each configuration option in the [Identity settings](#identity-settings) and [Provider settings](#provider-settings) sections. ### Configuration examples This section includes screenshots from the Conversion Service Configurator with configuration details of each signature type provided by the PKCS#11 cryptographic provider. - **PaDES-B-B**: Basic digital signature type that requires no time-stamp authority (TSA) nor revocation information (CRL, OCSP). - **PaDES-B-T**: Digital signature with a timestamp token. - **PaDES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. --- ### Identity settings The following sections describe specific configuration options in the identity section of the digital signature configuration. #### Common Name The name of the signing certificate. This is the common name of the certificate subject with limited support for placeholders. #### Thumbprint The SHA-1 thumbprint (also called fingerprint) of the signing certificate, with limited support for placeholders, is required for certificate selection. **note: If this value is incorrect, the error message in the service log is:** *"Certificate not found in store."*. The thumbprint value must be a string of hexadecimal digits and its characters must be in the ranges `0-9`, `a-f`, `A-F`, and spaces. You can directly use the **Thumbprint** value displayed in the Windows certificate dialog. Examples: - `005572a2d0242a0121c8dee341463a63ae9cabdf` - `00 55 72 A2 D0 24 2A 01 21 C8 DE E3 41 46 3A 63 AE 9C AB DF` Supported placeholders: - `[custom:]` - A custom placeholder. #### TSA The URL of the trusted TSA from which you acquire a timestamp. **note: Applying a time stamp requires an online connection to the time server and you must configure firewall accordingly.** If a web proxy is used, ensure the following MIME types are supported: - `application/timestamp-query` - `application/timestamp-reply` #### Fallback TSA If the primary TSA is unavailable, this fallback URL is used to get the timestamp instead. #### Add Revocation Information Whether to add revocation information (OCSP, CRL) to the document time-stamp signature. For example, to make a signature with enabled Long Term Validation (LTV). #### Signature-level The signature level is a general setting for every signature provider. Review [Signature level](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#signature-level) for more information. --- ### Provider settings #### Library The path to the PKCS#11 driver library (DLL). PKCS#11 is a standard interface offered by most cryptographic devices such as HSMs, USB tokens, or sometimes even soft stores (for example openCryptoki). #### Slot ID The ID of the slot that contains the signing certificate and its private key. If the slot ID is not defined, the first slot that contains a running token is used. #### Pin The PIN (password) required to access the private key. If it is not defined, the submission for the PIN is activated via the pad of the token. If this is not supported by the token, the following error message is raised when signing: "Private key not available." --- ## Swisscom All-in Signing Service The Swisscom cryptographic provider enables access to the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/). The service can then perform cryptographic functions such as signing a document. :::tip[Supported signature standards] The Swisscom cryptographic provider offers options to configure various digital signature types: - **PADES-B-T**: Digital signature with a timestamp token. - **PADES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. - **On-Demand**: Documents signed with a Qualified Electronic Signature (QES) benefit from the highest level of security and legal certainty. :::note[Prerequisite] This cryptographic provider implements the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/) methods and requires a Swisscom account for cryptographic signatures. Accounts with static and dynamic identities are supported. Swisscom Signing Service provides signing certificates using CMS (PKCS#7) signatures. ## Configure Swisscom All-In Signing Service The following sections introduce [Configuration example](#configuration-examples) and provide detailed descriptions of each configuration option in the [Provider settings](#provider-settings), [Identity settings](#identity-settings), and [On-demand settings](#on-demand-settings) sections. ### Configuration examples This section includes screenshots from the Conversion Service Configurator with configuration details of each signature type provided by the PKCS#11 cryptographic provider. - **PaDES-B-T**: Digital signature with a timestamp token. - **PaDES-B-LT/LTA**: Digital signature with a timestamp token and signature validation data. - **On-Demand**: Documents signed with a Qualified Electronic Signature (QES) benefit from the highest level of security and legal certainty. --- ### Provider settings When using Swisscom cryptographic provider, you require the SSL client certificate, private key, and password from your Swisscom account for cryptographic signatures. #### SSL Client Certificate Use the SSL client certificate in PKCS#12 format (`.p12` or `.pfx`). To generate the PKCS#12 format, combine the client certificate with its private key. **caution: It's highly advisable to protect the private key with a password.** #### Password Recommended with SSL client certificate: Enter the password to decrypt the private key of the SSL client certificate. #### Trust store [Trust store](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#trust-store) is a general settings among online signature providers. #### Address Provide the service endpoint URL. --- ### Identity settings #### Common Name The name of the signing certificate. This is the common name of the certificate subject. #### Identity Varies depending on the specific signature type: - **Document Time-Stamp**: The customer identity string provided by Swisscom, usually in the form of `""`. - **Long Term Document Signature**: The Claimed Identity string provided by Swisscom, typically follows the format of `":"`. The key identity must support the creation of static CMS Signatures. #### Signature-level The signature level is a general setting for every signature provider. Review [Signature level](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/#signature-level) for more information. #### Add revocation information Whether to add revocation information (OCSP, CRL) to the document time-stamp signature. For example, to make a signature with enabled Long Term Validation (LTV). --- ### On-Demand settings #### Distinguished Name The subject name of a certificate is a distinguished name (DN) that contains identifying information about the entity to which the certificate is issued. - CommonName (CN) and CountryName (C) are mandatory fields. #### Phone Number The mobile phone number of the user signing the documents. #### Message The text displayed to the user signing the documents. #### Message Language The language of the message content. --- **tip: Read more in the in-app documentation by clicking the information button in the configuration section header.** --- ## Configure stamps and annotations Learn how to configure the Conversion Service to add a barcode, image, and text stamp or annotation to pages of the output documents using the Conversion Service Configurator. **info: For more information about stamps and annotations, the differences between stamps, and the workflow specific settings, review **[Stamping in workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/stamping)**.** ## Procedure Configure stamps and annotations for a profile by following these steps: 1. In the **Conversion Service Configurator**, go to **Workflows & Profiles**. You can either: 1. Select a profile to edit by clicking the pen icon to edit the profile configuration. 1. Click **Add** to create a new profile from a selected workflow. 1. In the **Processing Steps** section, enable the **Stamp and Annotation** toggle. 1. When you enable the Stamping option for a profile, an additional configuration section appears that allows you to add different stamps for that specific profile. To add a new stamp or annotation follow these steps: 1. Click **Add Item** next to the **Stamp** or **Annotation** headers. 2. Choose the type of stamp or annotation you want to add to your profile. There are three types: - **Text**: Text stamps can be used to apply a single line of arbitrary text. For example, to create header or footer lines or to apply a transparent watermark. - **Image**: Image stamps can be used to apply an image, for example to apply a company logo. - **Barcode**: Barcode stamps can be used to apply a 1D or 2D barcode, for example to apply a stamp with the document ID. 3. Configure the options for the stamp type. Review section [Stamps and annotations configuration options](#stamps-and-annotations-configuration-options) 4. Determine the **layout for the stamp or annotation**. The position is determined by setting one or two adjacent values. For example, if only set the **bottom** value, the stamp is bottom-aligned to the configured distance to the bottom and horizontally centered. If the "top" and "right" values are set, the stamp is also be top-aligned and right-aligned to the configured border values. You can choose centimeters, millimeters or inches as the unit of measurement for expressing the position. - **Left**: Distance to the left border of the page. - **Top**: Distance to the top border of the page. - **Right**: Distance to the right border of the page. - **Bottom**: Distance to the bottom border of the page. - **Angle** (text stamp only): The angle of the stamp in degrees. Rotation is counter-clockwise. For example: - 0°: Horizontal text - 90°: Sideways bottom to top - -90°: Sideways top to bottom - 45°: Diagonal bottom-left to top-right - -45°: Diagonal top-left to bottom-right - 180°: Upside down - **Width** (image and barcode stamps only): Width of the stamp. - **Height** (image and barcode stamps only): Height of the stamp. For example, if only the "width" value is set for a 2D barcode, the height is calculated accordingly and the stamp is vertically and horizontally centered. :::note For 2D barcodes, at least the width or height of the stamp must be specified. For 1D barcodes, both values must be provided. ::: 5. Choose the **pages** on which you want to display the stamp: - **All**: the stamp is applied to all pages of all documents. - **First**: the stamp is applied to the first page of the main output document. An error is triggered if the resulting document is a collection. - **Last**: the stamp is applied to the last page of the main output document. An error is triggered if the output document is a collection. ### Stamps and annotations configuration options The configuration options depend on the stamp type. Review the following sections for more information: - Stamps: - [Image stamp](#image-stamp) - [Text stamps](#text-stamp) - [Barcode stamps](#barcode-stamp) - Annotations: - [Image annotation](#image-annotation) - [Text annotation](#text-annotation) - [Barcode annotation](#barcode-annotation) #### Image stamp - **Image**: Path of the image to be used as a stamp. The path must be an absolute path. Click the folder icon to open the file explorer. #### Text stamp - **Text**: Text to be displayed as a stamp. You can use [placeholders](#placeholders) to generate the text to be displayed when running the workflow. - **Font**: Type family and typeface. The list shows all fonts installed in the system. - **Font Size**: Size of the typeface displayed in the text stamp (points). - **Text Color**: Color of the text displayed in the stamp. Click the paintbrush icon to open the color picker tool. You can also choose a color by entering the hexadecimal RGB value, Hue-Sat-Lum value or web color name. For example, `DarkGreen` or `#FF0000` (equivalent to "Red"). - **Text Opacity**: Transparency of the text. The value can range from 0.0 to 1.0, where 1.0 is opaque and 0 is completely transparent. If you want the text stamp to be used as a watermark, use 0.5. :::note Transparency is not allowed in PDF/A-1. ::: - **Allow Scaling**: This option prevents the Conversion Service from adding a stamp outside of the page boundaries, ensuring that it is displayed on a page. By default, this option is set as false. If you allow scaling, the Conversion Service decreases the font size of your desired stamp to fit the page. :::note This option only works with horizontal stamps, where the angle is not specified or set to zero. ::: #### Barcode stamp - **Type**: The type of barcode to be displayed. You can choose from: - **1D barcode types**: EAN-13 and Code 128 - **2D barcode types**: QR code and data matrix **note: The barcode type may affect the width and height of the stamp defined in the Layout section.** - **Value**: The value of the barcode. If the barcode type is EAN-13, the value must be 12 digits or 13 digits with valid checksum. You can use [placeholders](#placeholders) to generate the barcode to be displayed when running the workflow. #### Image annotation - **Image**: Path of the image to be used as an annotation. The path must be an absolute path. Click the folder icon to open the file explorer. #### Text annotation - **Text**: Text to be displayed as an annotation. You can use [placeholders](#placeholders) to generate the text to be displayed when running the workflow. - **Font**: Type family and typeface. The list shows all fonts installed in the system. - **Font Size**: Size of the typeface displayed in the text annotation (points). - **Text Color**: Color of the text displayed in the annotation. Click the paintbrush icon to open the color picker tool. You can also choose a color by entering the hexadecimal RGB value, Hue-Sat-Lum value or web color name. For example, `DarkGreen` or `#FF0000` (equivalent to "Red"). - **Text Opacity**: Transparency of the text. The value can range from 0.0 to 1.0, where 1.0 is opaque and 0 is completely transparent. If you want the text annotation to be used as a watermark, use 0.5. :::note Transparency is not allowed in PDF/A-1. ::: #### Barcode annotation - **Type**: The type of barcode to be displayed. You can choose from: - **1D barcode types**: EAN-13 and Code 128 - **2D barcode types**: QR code and data matrix **note: The barcode type may affect the width and height of the annotation defined in the Layout section.** - **Value**: The value of the barcode. If the barcode type is EAN-13, the value must be 12 digits or 13 digits with valid checksum. You can use [placeholders](#placeholders) to generate the barcode to be displayed when running the workflow. ## Placeholders Customize the text of a text stamp, text annotation, value of a barcode stamp, and barcode annotation using placeholder variables. Placeholder variables whose name start with **custom:** are replaced with the value of the corresponding document option `CUSTOM.OPTION_NAME`. This placeholder is used to generate barcodes. Example: - The stamp text in the profile is configured as: **`Reviewed by [custom:REVIEWER]`**. - The document option `CUSTOM.REVIEWER` is set to **`John Doe`**. - The resulting stamp text is: **`Reviewed by John Doe`**. The supported placeholders are documented separately for each workflow. For more information about placeholders, find specific workflow documentation such as [Archive as PDF/A-2 workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2), [Convert to PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion), or [Create Dossier PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier), or [other workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/), and review available placeholders under the **Job and document options** header. --- ## Set up using the Configurator You can configure the Windows service in the **Conversion Service** tab of the **Conversion Service Configurator** application. You can view the [status](#status) of the service, configure the [host address](#service-host-address) and a [proxy](#proxy) (if required), set the [rules for Office conversion](#office-conversion), determine the path to store temporary files and logs, and indicate a database where statistics on the service's performance can be stored. **tip: To configure the service deployed in a Docker container, see [Set up the service in your Docker container](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container).** ## Status Shows the status of the service and provides the controls to start, stop, and restart the service. The status is *running* when the Windows service is started and the configuration is valid. If the service is not operable even though the Windows service has been started, check the log file for more information on the cause. Common problems are a missing license or low disk space. **note: Whenever the configuration is changed, the Windows service must be restarted for the changes to take effect.** When the service is stopped, all current jobs are canceled and deleted. The Windows service is installed with service name `ConversionService` and display name Conversion Service. Its status can also be changed using Windows' Services desktop app or the `sc` command line program. ## Windows Defender Rules The Conversion Service provides an optional feature to exempt its processes and working directories from monitoring by Windows Defender Antivirus. While not mandatory, it's advisable to enable this feature to enhance performance and improve stability. Windows Defender's real-time scanning can slow down the Conversion Service by continuously scanning files during document transformations. This [Microsoft Learn page](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/tune-performance-defender-antivirus?view=o365-worldwide) explains how real-time scanning can impact performance. By setting these rules, you reduce overhead and improve conversion speed. Enable this feature in the Configurator under the Conversion Service tab by checking "Windows Defender Rules.". To enable this feature, find more details in [Local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation) documentation. ## Ports Opens the port for connections from all other computers. The port configured in the **Service Host Address** section is by default available from the local machine only. If you want to access the service from other machines, e.g. using the shell client or the REST API, then you need to open a port in the Windows firewall. If more specific rules are required, you need to create them manually (see [API security](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api#api-security)) ## Service host address The address of the service host in the format `http[s]://‹hostname›:‹port›/conversion/v1.0/rest`. The default host address is `http://localhost:13033/conversion/v1.0/rest` You should not change the address unless the default port `13033` is already in use on the local machine. If the port is changed and firewall rules have been added, they must be changed accordingly. You cannot configure the suffix `conversion/v1.0/rest`. The configured service host address is also the endpoint URL used by the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) and the [REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api). ## HTTPS By default, the service endpoint uses HTTP. Activating HTTPS disables support for HTTP to prevent clients from accidentally sending sensitive information over HTTP. HTTPS can be activated by setting the scheme of the service host address to `https`. In addition, the following is required: - A **valid host certificate**. The certificate must be provided as PKCS\#12 file (`.pfx` or `.p12`) that includes the certificate's private key and issuer certificates. If the private key is password protected, the password must be configured. - The **host name**. The `‹hostname›` of the service host address must be set to the name of the host certificate. Otherwise, clients such as the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) refuse to connect. This hinders correct operation of many components, including the Configurator GUI or the [Connection configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections). - A **trusted host certificate**. To activate the HTTPS for [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-json) and [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http): 1. In the Conversion Service Configurator, go to the **Conversion Service** tab. 1. In the **Configuration** section, enable the **Use for Connectors** toggle. This toggle automatically changes endpoints of all configured REST Input connectors to HTTPS schema, applies the configured certificate, and disables support for HTTP. ## Connector service host address The default host address of the Connector Service is `http://localhost:13034/`. You can change this address in the following format: `http[s]://‹hostname›:‹port›/` **info: Change the Connector Service address only when the default port `13034` is already in use on the local machine. If you change the port, also adjust your firewall rules to ensure the Connector Service's correct function.** ## Temporary Files This is the directory where temporary files are written to. To optimize performance, this directory should be on a local drive with fast read and write access. ## Proxy Configuration of the proxy URL to be used for all HTTP and HTTPS communication to external hosts. The option can either be left empty for no proxy or must be a string with the following syntax: `http[s]://[‹user›[:‹password›]@‹host›[:‹port›]` Where: - **http/https**: Protocol for connection to proxy. - **‹user›:‹password›** (optional): Credentials for connection to proxy (basic authorization). - **‹host›**: Hostname of proxy. - **‹port›**: Port for connection to proxy. ### Email proxy Set a proxy URL for email communications. Route all email-related components through a defined URL proxy. The proxy server must support the CONNECT HTTP method to enable the IMAP and SMTP protocols. To enable the email proxy: 1. In the Conversion Service Configurator, go to **Conversion Service** tab. 1. Provide the proxy URL in the **Proxy** field. 1. Enable the **Use for emails** toggle. Connectors that are routed through this proxy are: - Watched Mailbox (Exchange Online) - Watched Mailbox (IMAP) - Output Mailbox (Exchange Online) - Output Mailbox (IMAP) - Send Email (Exchange Online) - Send Email (SMTP) ## Office conversion Configure the service to convert Word, Excel and PowerPoint to PDF conversion. Click **Configure**. For more information, see [Office conversion](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). ## Log directory The directory where all log files are written to. This includes the log files of the service (see [Service log](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log)), the connectors, and the configurator. ## Statistics Configure whether the service stores service, job, and task information to a database file to analyze the conversion history with the [Statistics](https://www.pdf-tools.com/docs/conversion-service/monitor/statistics) tab. The location of the database is configured in the **Database directory** setting. ## Database directory The directory where the database is stored when the **Statistics** setting is enabled. This setting is only configurable when the **Statistics** setting is turned on. ## Max. age The configured maximum age of the database entries. Information of the conversion history will be deleted after reaching the maximum age. This setting is only configurable when the **Statistics** setting is turned on. ## Max. file size The configured maximum file size of the database. Older entries of the conversion history will be deleted if the maximum database file size is exceeded. This setting is only configurable when the **Statistics** setting is turned on. --- ## How the Conversion Service works The Conversion Service can be thought of as a factory with a production line (workflow) for each product it offers. The products it manufactures are documents prepared for a specific use case. For example, the workflow Archive PDF/A-2 is engineered specifically for preparing documents for archiving. For example, a production line consists of a series of processing steps (e.g. validate, OCR, convert, merge, sign, etc.). Each step moves the raw materials (input documents) closer to being a finished product (output document). Some steps are optional and most of them have options (e.g. paper size, image resolution, ...). These can be adjusted to your individual needs by configuring one or more setups (profiles) for each production line. A profile defines which processing steps to activate and what options to use. If you want the factory to manufacture a product (**output document**), you send them an order (**job**) consisting of the raw materials (**input documents**), the production line (**workflow**), and setup (**profile**) to use and where to deliver the finished product (**output path**). #### Input Similarly, to prepare documents for a specific use case, you send a job consisting of the following input to the Conversion Service: - **Input documents**: The documents to be processed. - **Workflow name**: Which workflow to use, i.e. the use case to prepare the documents for. - **Profile name**: Which profile to use, i.e. how the documents should be processed. - **Output path**: Where to store the resulting document. #### Output Once conversion is completed, the Conversion Service returns: - **Output document**: If the conversion was successful, the resulting document can be found in the specified output directory. - **Report**: Conversion events, warnings, and errors. Useful for analysis. ### Integrate in your workflow The communication with the factory can happen through different channels. Maybe you send the order by mail. Or you bring everything to the factory in person. Similarly, the Conversion Service offers different interfaces to communicate through. The Conversion Service is designed to be installed on a server and integrated into your system using one of the interfaces listed in **[Integrate the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/integrate/)**. --- ## Configure OCR The optical character recognition (OCR) technology identifies characters in images, scanned documents, and documents containing images with text. It adds a text layer containing recognized characters without visual changes to the original documents. The OCR can make all text in PDF documents extractable, regardless of how the text is included. Enable OCR in a Conversion Service Workflow to enhance the processed documents with information detected by an OCR engine. The Conversion Service OCR can process files that already include an OCR layer. Learn how to install, configure languages recognized by the OCR, and learn about various configuration parameters of the Pdftools OCR Service in the following guides. **Recommended: Use the [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/)** for a new OCR workflow and profile configuration. --- ## Legacy 3-Heights® OCR Service **warning: As of version **6.4.0+**, you can use the Conversion Service with the Pdftools OCR Service. The configuration described on this page is legacy. If you are setting up a new OCR workflow, refer to [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) for the current solution.** You can configure OCR scans to be compatible with the **3-Heights® OCR Service**. Use this configuration only if your Conversion Service and a Document Converter installation use an ABBYY license simultaneously. For more information about the configuration of the legacy 3-Heights® OCR Service, review [Migrating from 3-Heights® Document Converter](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) documentation. --- ## Legacy OCR using your own ABBYY license key **warning: As of version **6.4.0+**, you can use the Conversion Service with the Pdftools OCR Service. The configuration described on this page is legacy. If you are setting up a new OCR workflow, refer to [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) for the current solution.** ## Install ABBYY :::info[Prerequisites] To use OCR in the Conversion Service, you need: - A Windows Server machine to install the ABBYY FineReader OCR Engine. - An ABBYY OCR license issued by Pdftools. Use the [Contact form](https://www.pdf-tools.com/contact/) if you require a license. - The ABBYY FineReader Engine installer from the **Legacy Products** section of the [Pdftools Portal](https://portal.pdf-tools.com/). The installer is listed as **3-Heights® OCR Service for ABBYY FineReader** with your version number. The Conversion Service supports ABBYY FineReader Engine v11 and v12. Install the OCR Engine on the Windows Server machine using the Pdftools ABBYY FRE installer. After installation, **activate your ABBYY license**. ### Activate ABBYY license There are two types of ABBYY licenses: - **[Online license](#online-license)** - **[Standalone license](#standalone-license)** #### Online license ABBYY offers **online licenses**. If you purchased an online license through Pdftools, **contact Pdftools support**. Our support will guide you through the license activation process. When you receive the online license, we will send you an email message forwarding ABBYY’s email. This email message includes a **ZIP file** (for example, `SWATXXXXXXXX.zip`) containing `password.txt` and `SWATXXXXXXXXX.ActivationToken`. #### Standalone license Activate the standalone license using the following steps: 1. Open the **ABBYY License Manager**. 2. Click **Activate License**. 3. Insert the **ABBYY license key** and complete activation. **note: If you have the online license type and try to activate it using these steps reserved for the standalone license type, your online license can be locked. In such a case, please contact Pdftools support to resolve the issue. ** #### Summary - **[Online license](#online-license)**: Contact Pdftools support for activation. - **[Standalone license](#standalone-license)**: Activate using the ABBYY License Manager. ## Enable and configure OCR **info: You can only activate OCR processing for the **archive** and **conversion** workflows.** The following steps explain how to activate and configure OCR in a profile: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 2. Choose a profile where you want to activate the OCR, and then edit or duplicate this profile. 3. Enable the **OCR Settings** processing toggle. 4. Navigate to the now visible configuration section **OCR Settings**. 5. In the **OCR Settings** section, click the **Add Item** button. 6. Select the version of the ABBYY FineReader Engine you installed, and then click on **Next**. 7. Confirm the values with **Apply**, or configure the OCR engine in more detail following the instructions in the following section. :::tip[Built-in documentation] For more information about the resulting page rendering configuration, such as the resolution, image processing, and text processing details, refer to the built-in documentation within the Conversion Service Configurator. To access built-in documentation, click the icon next to the **OCR Settings** configuration section header. ### Configure ABBYY FineReader Engine Change the predefined profile for ABBYY FineReader Engine, add a custom profile, or configure languages the OCR scans for: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 2. Choose the profile where you activated the OCR. 3. Navigate to the configuration section **OCR Settings**. 4. In the **OCR Settings** section, click the **Add Item** button. 5. Select the version of the ABBYY FineReader Engine you installed, and then click on **Next**. 6. Change the custom profile, predefined profile, or language that OCR scans for in the window **Step 2: Configure Selected Engine**. See the sections below for more information about each of these procedures. **info: To change a language the OCR must identify, use the **internal name** from [Predefined Languages in ABBYY FineReader Engine](https://help.abbyy.com/en-us/finereaderengine/12/user_guide/specifications_langnames/) in the ABBYY FineReader documentation.** **tip: Review the following sections for more information about the configuration of the ABBYY FineReader PDF.** #### Predefined profile The ABBYY predefined OCR engine profiles are designed for specific use cases. | Profile Name | Description | | ------------------------------- | ----------------------------------------------------------------- | | Default | The default ABBYY profile. | | Document Conversion (Accuracy) | Optimized for accuracy. Convert documents into editable formats. | | Document Conversion (Speed) | Optimized for speed. Convert documents into editable formats. | | Text Extraction (Accuracy) | Optimized for accuracy. Extract text from documents. | | Text Extraction (Speed) | Optimized for speed. Extract text from documents. | For more information, see the [Predefined profiles](https://help.abbyy.com/en-us/finereaderengine/12/user_guide/guidedtour_profiles/#predefined_profiles) in the ABBYY documentation. **tip: Select the standard profile or the most suitable profile for your use case. Adjust individual configuration values to your needs using a custom profile.** #### Custom profile With a customized profile, you can adjust individual configuration options of the OCR Engine according to your requirements. Create your customized profile as an INI file and enter the path to this file in the custom profile field. The configuration values of the customized profile take precedence over the preset values of the selected predefined profile. **info: Pdftools integration of the ABBYY OCR Engine is custom. Some options (for example, `PDFExportParams`) do not affect the OCR result.** For more information about custom profiles, see [User profiles](https://help.abbyy.com/en-us/finereaderengine/12/user_guide/guidedtour_profiles/#user_profiles) in the ABBYY documentation. #### Language configuration Configure all languages that appear in your documents to improve optical recognition accuracy. :::tip[Configure all languages included in the documents] The ABBYY FineReader Engine only recognizes characters that are used in the languages you configured. For example, if you only choose **English**, some special characters like German umlauts (äöü) are not identified correctly and can be identified as different letters (aou). Choose the languages used in the documents to avoid such mistakes. See the [Predefined Languages in ABBYY FineReader Engine](https://help.abbyy.com/en-us/finereaderengine/12/user_guide/specifications_langnames/) in the ABBYY documentation. --- ## Convert Microsoft Office files The Conversion Service offers three options for converting Word, Excel, and PowerPoint documents to PDF: - **[Standard Converter](#standard-converter-default)** (default): Converts Office documents without requiring Microsoft Office or any additional license. Works on both Windows and Docker. - **[Local Microsoft Office installation](#local-microsoft-office-installation)**: Highest visual fidelity using Microsoft Office COM automation. Windows only. - **[Office for the web service](#office-for-the-web-service)**: Cloud-based conversion using Microsoft Azure. Works on both Windows and Docker. ## Choose a conversion method Use the **[Standard Converter](#standard-converter-default)** (default) if you: - Need Office conversion that works without additional setup or licenses out of the box. Use the **[local Microsoft Office installation](#local-microsoft-office-installation)** if you: - Require the highest visual fidelity with pixel-perfect layout preservation. - Need to convert large documents (more than 100 MB). - Want to process many large Excel files. - Only the local installation option supports **fit to page** in Microsoft Excel. - Microsoft Excel files with many sheets or hundreds of pages aren't supported in the Office for the web service. - Must repair Word documents. - Work with password-protected documents. - Need to convert binary PowerPoint formats (PPT, PPS) or WordML/SpreadsheetML (XML-based) formats. - Need to use special or custom fonts. - Fonts can be installed locally but not added to the web service. - The web service includes more default fonts than a typical Windows server. - Keep data on-premise if required by security policies or if you require a lack of internet access. - Web service conversions temporarily store files in the Azure cloud. Storage region depends on your subscription. Use the **[Office for the web service](#office-for-the-web-service)** if: - You're converting smaller files (smaller than 100 MB), especially Word documents. - Files were created using Microsoft Office for the web. - You prefer lower setup and maintenance overhead. --- ## Standard Converter (default) The Standard Converter converts Word, Excel, and PowerPoint files without a Microsoft Office installation or license. It's enabled by default on fresh installations. ### Supported input formats - Microsoft Word: DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF - Microsoft Excel: XLS, XLT, XLSX, XLSM, XLTX, XLTM - Microsoft PowerPoint: PPTX, PPTM, PPSX, PPSM ### Limitations The Standard Converter doesn't support: - Binary PowerPoint formats (PPT, PPS) - Password-protected or encrypted documents - WordML/SpreadsheetML (XML-based legacy formats) For these formats, configure a [local Microsoft Office installation](#local-microsoft-office-installation) or the [Office for the web service](#office-for-the-web-service). ### Configuration options Configure the Standard Converter in the **Standard Converter Settings** section in the Conversion Service Configurator. These settings are organized by document type: - **Word Settings** - **Track Changes (Redlining)**: When enabled, renders revision marks (insertions, deletions, and formatting changes) in the converted PDF. - **Excel Settings** - **Allow Scaling**: When enabled, scales worksheet columns to fit on one page. The Standard Converter automatically embeds fonts in the output PDF for consistent rendering across Windows and Docker (Linux). ### Fonts in Docker The Conversion Service Docker image includes fonts that cover common Office document fonts, including metric-compatible replacements for Calibri, Cambria, and other Microsoft Office fonts. Documents retain their original line breaks and page layout during conversion. If a font used in the document isn't available, the Standard Converter automatically substitutes the closest available alternative. #### Add custom fonts If your documents use corporate or proprietary fonts, mount a font directory into the container: ```bash docker run -dp 13033:13033 \ -v /PATH_TO_YOUR_CUSTOM_FONTS:/usr/local/share/fonts/custom \ pdftoolsag/conversion-service ``` Replace `PATH_TO_YOUR_CUSTOM_FONTS` with a path to your custom font. As a result, Standard Converter automatically detects fonts in `/usr/local/share/fonts/custom` at startup. --- ## Local Microsoft Office installation A local Microsoft Office installation is the pixel-perfect Office conversion option. Configure it only if the [Standard Converter](#standard-converter-default) doesn't meet your fidelity, format, or feature requirements. **caution: To comply with Microsoft licensing, each client submitting Word, Excel, or PowerPoint jobs must be licensed for Microsoft Office.** For more information, see [Licensing Microsoft Office software in Commercial Licensing on the Microsoft site](https://download.microsoft.com/download/3/d/4/3d42bdc2-6725-4b29-b75a-a5b04179958b/licensing_microsoft_office_software.pdf). If you want to convert files using local Microsoft Office installation, you must have a compatible version of Microsoft Office installed on the Conversion Service server: | Office version | |----------------------| | Office 2021 (64-bit) | | Office 2024 (64-bit) | | Microsoft 365 (64-bit) | The supported language is **English (United States)**. The **Microsoft Print to PDF** virtual printer must also be installed. :::note[Microsoft Office version compatibility] For optimal conversion results, use the same Microsoft Office version that was used to create the documents. The Conversion Service only supports Microsoft Office 2021 and later. ### Install and configure local Microsoft Office installation During Microsoft Office setup, follow these steps and requirements: 1. Use a **static license key** (device-based license), especially with Microsoft 365. Avoid user logins to prevent dialog pop-ups that can interrupt processing. 1. After installation, [activate the Office license](https://support.microsoft.com/en-us/office/activate-office-5bd38f38-db92-448b-a982-ad170b1e187e). 1. Open sample Word, Excel, and PowerPoint files to confirm there are no blocking pop-ups. 1. If your documents rely on language features like **hyphenation**, install the required language packs. :::note[Improve performance with Windows Defender exceptions] If Windows Defender is active, enabling the Windows Defender Rules setting in the Configurator may improve conversion speed. It adds exceptions for specific processes and folders to reduce scanning overhead. Enable it under **Conversion Service > Windows Defender Rules**. Make sure group policies don't override these exceptions. :::info[Third-party antivirus software] Third-party tools like Bitdefender may block required operations. To guarantee successful conversion, you must add any application exceptions to your third-party antivirus software. #### Set up on Windows Assign a user account for the local Microsoft Office installation. You can either: - Recommended: Use **automatically generated** user account - **Existing** user account ##### Recommended: Use automatically generated user account Unless restricted by security policies or domain controllers, let the Conversion Service Configurator create a `ConvsrvOfficeUser` account with a secure password. The following settings are applied automatically: - Joins the `Users` group. - Has encrypted credentials saved through the Windows Data Protection API. - Grants the user **Allow log on locally** and **Log on as a batch job** security policies. - Has registry and DCOM permissions for Word, Excel, and PowerPoint. To set up an automatically generated user account in the Configurator: 1. In the **Conversion Service Configurator**, go to the **Conversion Service** tab, and then find the **Configuration** section. 1. If the Standard Converter is configured, next to **Office Conversion** click **Remove**. 1. Next to **Office Conversion**, click **Configure**. 1. Select **Local Office Installation and Automatically Create a User Account**, and then click **Next**. 1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**. 1. *ConvsrvOfficeUser* appears in the username field with a random password. Click **Apply**. **note: The automatically generated user account is recommended for most servers unless specific security policies or domain controller restrictions apply. This is the case if:** - [Log on as a batch job](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/log-on-as-a-batch-job) security policy is applied. - [Allow log on locally](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/allow-log-on-locally) security policy is applied. - The server is managed by a domain controller. ##### Use an existing user account Use this if your server has strict security rules or is managed through a domain controller. Requirements: - Create the user account manually (local or domain). The Conversion Service Configurator does not modify this account. - Grant **[Allow log on locally](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/allow-log-on-locally)** and **[Log on as a batch job](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/log-on-as-a-batch-job)** (or assign to a group with these rights). - Don't assign admin privileges. Set up the user account with minimum user rights (don't assign the user account to the Administrators group). - Update the configuration if the password changes or expires. These properties and settings are set automatically: - The password is encrypted using the Windows Data Protection API before it is stored in a configuration file. - The registry and DCOM permissions for Word, Excel, and PowerPoint are adjusted. **caution: If using a domain user, **disable any group policies enforcing regular password changes**. Otherwise, you'll need to reconfigure the Office setup each time the password changes.** To set up an existing user account in the Configurator: 1. In the **Conversion Service Configurator**, go to the **Conversion Service** tab, and then find the **Configuration** section. 1. If the Standard Converter is configured, next to **Office Conversion** click **Remove**. 1. Next to **Office Conversion**, click **Configure**. 1. Select **Local Office Installation with an Existing User Account**, and then click **Next**. 1. Enter the username and password for the user account. The Conversion Service accepts all standard formats for Windows users (both `Username@domain` and `domain\Username` formats). The `Username` is automatically resolved to `ServerName\Username`. 1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**. #### Set up in Docker container Send Office documents to another Conversion Service instance running on Windows. Office document conversion can be activated as follows: 1. Set up and run the service on Windows. 2. Enable Office Conversion in the Processing Steps section of your profile. Note that this is active by default. 3. When starting the Docker container, set the **WINDOWS_SERVICE_ENDPOINT** environment variable: ```bash docker run -dp 13033:13033 ... \ -e WINDOWS_SERVICE_ENDPOINT=http://server:13033/conversion/v1.0/rest \ pdftoolsag/conversion-service ``` Note that if the Windows service uses HTTPS, its host certificate must be trusted by the Docker container. Otherwise, no connection can be established. By default, no trusted certificates are installed. 4. Copy trusted certificates to **/usr/local/share/ca-certificates/**. 5. Run the command **update-ca-certificates**. ## Office for the web service The [Office for the web service](https://learn.microsoft.com/en-us/office365/servicedescriptions/office-online-service-description/office-online-service-description) option converts the documents using a Microsoft Azure Cloud service. Technologies used with this option include the Microsoft Authentication Library (MSAL), the Microsoft Graph API, and the Microsoft Sharepoint API. The conversion flow: 1. Upload the file to the user's OneDrive. 2. Convert the file to PDF. 3. Delete the uploaded file. All connections use HTTPS. The service encrypts files before transmitting them over the internet. **caution: You need a valid license to allow the Conversion Service to convert Word, Excel, and PowerPoint documents. This means you must have:** 1. **Microsoft 365 for business subscription** (Azure Cloud tenant) with a dedicated user account. 2. **Microsoft 365 license** for this dedicated user. You should create a dedicated user account, as full control over this user's OneDrive is requested. ### Set up on Windows Use the Configurator to set up the Office for the web: 1. In the **Conversion Service Configurator**, go to the **Conversion Service** tab, and then find the **Configuration** section. 1. If the Standard Converter is configured, next to **Office Conversion** click **Remove**. 1. Next to **Office Conversion**, click **Configure**. 1. Select **Office for the web**, and then click **Next**. 1. Enter the user account login (usually, an email address) for the Microsoft Office for the Web Service in the **Username** field. 1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**. 1. Sign in to the Microsoft 365 user account in the pop-up window that appears. Enter the password for the user account. If your company has set up 2-factor authentication, enter the authenticator code and click **Verify**. ### Set up in Docker :::tip[Prerequisites] Before you start, you need: - An account for Microsoft Office for the web. - A Conversion Service profile with Office Conversion enabled. Most profiles have this option enabled by default. For more details, see [Configure and export a profile](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker#configure-and-export-a-profile). - A working Conversion Service Docker setup. For more details, see [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker). You can configure Office for the web in Docker with either Docker Compose or the `docker run` command. Use Docker Compose if you already manage the Conversion Service through `docker-compose.yaml`. Use `docker run` for standalone container setups or quick tests. #### Set up using Docker Compose 1. Edit the `docker-compose.yaml` to add the Office for the web environment variables and a persistent volume for the authentication token cache: ```yaml volumes: vol-conversion-srv-app-data: {} services: conversion-service: image: pdftoolsag/conversion-service:IMAGE_VERSION environment: LICENSEKEY: LICENSE_KEY_VALUE LICENSINGSERVICE: http://LGS_IP_ADDRESS:9999 IMPORT_PROFILES: /etc/convsrv/PROFILE_EXPORT_FILE SERVICE__OFFICE__TYPE: OfficeWebService SERVICE__OFFICE__USERNAME: YOUR_OFFICE_USERNAME ports: - "13033:13033" volumes: - HOST_PROFILE_DIR/PROFILE_EXPORT_FILE:/etc/convsrv/PROFILE_EXPORT_FILE - vol-conversion-srv-app-data:/etc/convsrv ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `LGS_IP_ADDRESS`: The IP address of the machine running the Licensing Gateway Service. Use `9999` as the recommended port. - `HOST_PROFILE_DIR`: The directory on the host machine that contains the exported profile (for example, `C:/Users/john-doe/Desktop`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). - `YOUR_OFFICE_USERNAME`: The Microsoft 365 account used for Office for the web conversion. 1. In the directory containing `docker-compose.yaml`, start the container: ```bash docker compose up -d ``` 1. List the running containers and copy the Conversion Service container ID: ```bash docker ps ``` :::note Each `docker compose up -d` generates a new container ID. Copy the current ID before running the next steps. ::: 1. Grant the Conversion Service user access to the token cache volume: ```bash docker exec -u root CONTAINER_ID_OR_NAME chown convsrv:convsrv /etc/convsrv/ ``` Replace `CONTAINER_ID_OR_NAME` with the container's name or ID. 1. Initialize the authentication token cache: ```bash docker exec CONTAINER_ID_OR_NAME ./bin/csconfig office webinit ``` The output contains a sign-in URL and a one-time code. 1. Open the provided link, enter the code, and sign in with the account you set as `SERVICE__OFFICE__USERNAME`. If your organization requires multi-factor authentication, complete the prompt. #### Set up using docker run 1. Enable **Office Conversion** in the [Processing Steps section of your profile](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles#exporting-profiles). This option is active by default. 1. Create a persistent volume to store the authentication token cache: ```bash docker volume create --name convsrv-etc ``` 1. Mount the volume, create the `TokenCaches` folder, and grant the Conversion Service user read and write access: ```bash docker run --rm \ --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \ --user root pdftoolsag/conversion-service \ bash -c "mkdir /etc/convsrv/TokenCaches && chown convsrv:convsrv /etc/convsrv/TokenCaches" ``` 1. Initialize the token cache by running the `csconfig` tool: ```bash docker run \ --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \ -e SERVICE__OFFICE__TYPE=OfficeWebService \ -e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \ pdftoolsag/conversion-service \ bash -c "bin/csconfig office webinit" ``` 1. Start the Docker container with the token cache volume mounted and the required environment variables set: ```bash docker run -dp 13033:13033 \ --mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \ -e SERVICE__OFFICE__TYPE=OfficeWebService \ -e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \ pdftoolsag/conversion-service ``` Set `SERVICE__OFFICE__TYPE` and `SERVICE__OFFICE__USERNAME` to match the configured user and Office type. --- ## Troubleshooting Microsoft Office file conversion Learn how to troubleshoot Microsoft Office file conversion issues. This page applies only for the **local Microsoft Office installation**. This page includes two main sections targeted at: - **Specific issues**: If you have a specific error code or an error message, review [Troubleshooting steps](#troubleshooting-steps) section to resolve your issue. - **General issues**: If the resolution to your issue is still unclear, you can manually investigate the issue to speed up the support process. Review [Manual investigation](#manual-investigation) for more details. ## Troubleshooting steps You may encounter problems when setting up and using Office conversion. The issues can be divided into two categories: - [Configuration errors](#configuration-errors) - [Specific errors related to Word, Excel, and PowerPoint documents](#specific-errors-related-to-word-excel-and-powerpoint-documents) If this documentation doesn't resolve your issue, contact the [Pdftools support](https://www.pdf-tools.com/docs/support/). ### Configuration errors The following sections include the warnings and errors you encounter inside the Configurator during configuration and possible solutions. #### Microsoft Office is not installed Solution: The conversion of Word, Excel, and PowerPoint documents to PDF requires installing Microsoft Office on the same server where the Conversion Service is installed. Install a compatible Microsoft Office version (see *compatible Microsoft Office versions*). #### Microsoft Office is installed but not detected The Configurator shows that Office conversion is activated and the Office user is set, but a **Configuration Error** states that Microsoft Office is not installed. The log file contains entries similar to the following: ``` Installed Office Version Information: Version No Office, Platform: , ProductReleaseIds: , Word filepath: . Microsoft Office is not installed. Failed to remove office user. NoMatchingPrincipalException User 'ConvsrvOfficeUser' could not be found. ``` However, Microsoft Office is installed. Solution: Repair the Microsoft Office installation: 1. Open **Windows Settings** > **Apps**. 1. Find **Microsoft Office** in the list of installed applications. 1. Click **Modify**. 1. Select **Quick Repair** and click **Repair**. 1. After the repair completes, open the Conversion Service Configurator and verify that the Office configuration is detected correctly. #### 3-Heights Document Converter installation detected Solution: It is not recommended that the Conversion Service and the 3-Heights Document Converter be operated in parallel on the same server because the Office configurations of the two services interfere with and break each other. #### User validation failed Solution: This error usually occurs when the user domain is not recognized. Check the spelling and specify the domain by writing the username in SAM or UPN format, for example, *YourDomain\\YourDomainUser* or *YourDomainUser@YourDomain.com*, respectively. #### Trust relationship failed Solution: This error usually indicates a connection issue between the server and the domain controller. Check that the server where the Conversion Service is installed is a member of the domain you are trying to access. #### Office configuration problem in Configurator Solution: This message can occur when a setting related to the Office Configuration was changed after the Office User was configured. Try configuring the Office user again. If the problem persists or another error occurs, contact Pdftools support. #### The user name or password is incorrect when using a domain user account The Office conversion suddenly stops working when using a [domain user account](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation). In this case, the error is usually caused by a password group policy that regularly forces password changes. You need to disable the group policy for that domain user. ### Specific errors related to Word, Excel, and PowerPoint documents The following sections include errors that are associated with the use of the Microsoft Office application. #### The document is corrupt or a pop-up dialog window blocks the conversion process Solution: This error may occur if the document is corrupt or a pop-up blocks the conversion process. It occurs when no progress in the conversion of the Office document is observed for a certain amount of time. If the error was triggered by a pop-up dialog box blocking the conversion process, the problem may sometimes be resolved by manually opening and editing the document. #### The application WINWORD exceeded the memory limit of 2048 MB Solution: This error indicates that, during the conversion of a Microsoft Word document (for example DOCX), the application process (Microsoft Word) required more than 2048 MB of memory. The Conversion Service set this limit as a precaution to support the overall stability of the conversion process. For further assistance, contact support. Include the input file in the support ticket. #### Conversion of `test.docx` to PDF failed COM Exception: (0x80004005) If you use Microsoft Windows Defender or another third-party antivirus software, the conversion process for Office may fail, particularly when using Microsoft Excel. If this is the case, check: - Windows Defender Rules are enabled in the Configurator. - Any exceptions in the Windows Defender Rules are not forbidden by group policy. - Any exceptions are added to any third-party antivirus software (for example, Bitdefender). #### COM Exception: (0x800a18a0): You are attempting to open a file type `xxx` that has been blocked by your File Block settings in the Trust Center. This error occurs when the Trust Center settings block the file. Solution: The settings can be adjusted by opening Word (or Excel) as the configured Office User and [changing the File Block settings in Office](https://learn.microsoft.com/en-us/office/troubleshoot/settings/file-blocked-in-office). After performing this change, you need to restart the service. #### Excel conversion fails with a “Generic” error (COM exception 0x800a03ec) The printer spooler or Microsoft Print to PDF may cause this error. Both are required for Office conversion. If you encounter this error, ensure: - The Printer Spooler service **is** enabled. - [How to Add or Reinstall the Microsoft PDF Printer](https://answers.microsoft.com/en-us/windows/forum/all/how-to-add-or-reinstall-the-microsoft-pdf-printer/70377c34-e50a-42be-b9f3-92345d6e25df). Windows Server **version 26100.1742** is missing the Microsoft Print to PDF completely. Review the [How to Add or Reinstall the Microsoft PDF Printer](https://answers.microsoft.com/en-us/windows/forum/all/how-to-add-or-reinstall-the-microsoft-pdf-printer/70377c34-e50a-42be-b9f3-92345d6e25df) for solution. #### The server process could not be started because the configured identity is incorrect (COM exception 0x8000401a) Office conversions started to fail regularly. After reconfiguring the office user, it's working again for the next couple of days until it starts failing again. To fix the issue, follow these steps: 1. Use the `configuration.office repair` CLI command as administrator to automatically repair the configuration. 1. To prevent the Office user from being removed from the **Log on as a batch job** policy, add the user to a group that has this permission and is not routinely reset or cleared by maintenance scripts or policies. #### Access is denied (COM exception 0x80070005) This error may occur after configuring the Microsoft Office user using the Conversion Service Configurator. The full message saved to log files states: *Retrieving the COM class factory for component with CLSID {`000209FF-0000-0000-C000-000000000046`} failed due to the following error: 80070005 Access is denied.* To fix the issue: 1. Restart the machine. #### Server execution failed (COM exception 0x80080005) Office conversions started to fail regularly. The full message saved to log files states: *COMException Retrieving the COM class factory for component with CLSID {`000209FF-0000-0000-C000-000000000046`} failed due to the following error: 80080005 Server execution failed (0x80080005 (CO_E_SERVER_EXEC_FAILURE)).* To fix the issue: 1. Follow [5. DCOM configuration check](#5-dcom-configuration-check). 1. In your CMD, run: ```shell configuration.office repair ``` 1. Restart the machine. ## Manual investigation Investigate the issues of your Microsoft Office file conversion in the Conversion Service. If the error messages are unclear or none at all, and you cannot find the resolution in the [Troubleshooting steps](#troubleshooting-steps) section, the steps described in the following sections can help you find a solution or speed up the support case, as you can share the results of your manual investigation directly with our support team. Review the following steps: 1. [Microsoft Office license and activation](#1-microsoft-office-license-and-activation) 1. [User rights verification](#2-user-rights-verification) 1. [Service status check](#3-service-status-check) 1. [Antivirus and Group Policies](#4-antivirus-and-group-policies) 1. [DCOM Configuration check](#5-dcom-configuration-check) 1. [Office configuration validation](#6-office-configuration-validation) 1. [Manual PDF export](#7-manual-pdf-export) 1. [Local user test](#8-local-user-test) 1. [Additional troubleshooting steps](#9-additional-troubleshooting-steps) ### 1. Microsoft Office license and activation Ensure to run **Word**, **Excel**, or **PowerPoint** as the user configured for Office conversion in the Conversion Service Configurator, by following these steps: 1. Optional: If you have chosen to create a new Office user automatically in the Configurator (`ConvsrvOfficeUser`), in your command-line interface (CMD), run the following command as administrator to get the Office user password: ```shell configuration.office -d ``` 1. Click the Windows start button, and search for either **Word**, **Excel**, or **PowerPoint**. 1. Right click, select **Run as different user**. 1. Use the name and the password of the Office user. 1. Check and accept activation pop-ups (especially in the case of Excel). ### 2. User rights verification Verify whether the user configured for Office conversion has the correct user rights by following these steps: 1. Go to **Windows Search** > **Local Security Policy** > **Local Policies** > **User Right Assignments**. 1. Ensure the user is configured for Office conversion, or the user group it belongs to has the following rights: - **Log on as a batch job** - **Allow log on locally** ### 3. Service status check 1. Open the **Task Manager** > **Services**, and then ensure that the following services are running: - `seclogon`: Secondary Logon Service - `RpcSs`: Remote Procedure Call - `Spooler`: Print Spooler ### 4. Antivirus and Group Policies 1. In the Conversion Service Configurator, open the **Conversion Service** tab, and then enable the **Windows Defender Rules** toggle. 1. Some organizations have a group policy that doesn't allow this configuration. Re-open the Configurator and check if the **Windows Defender Rules** toggle is still enabled. If the setting is disabled again, the organization must change the group policy. 1. Optional: Do you have another active antivirus software? Fix its rules manually or disable the antivirus. ### 5. DCOM configuration check 1. **Windows Search** > **DCOMCNFG** > **Computers** > **My Computer** > **DCOM Config**. 1. Follow these steps for each of the following entries. Right click > **Properties** > **Security** > click **Edit** to all three displayed options and check whether the configured Office user is listed there. Check this in the following entries: - Microsoft Word 97 - 2003 Document - Microsoft Excel Application - Microsoft PowerPoint Slide - If any pop-ups are displayed, accept them and reconfigure, or run the following command in your CMD as administrator: ```shell configuration.office repair ``` 1. Check the **Identity** tab in all three entries (Microsoft Word 97 - 2003 Document, Microsoft Excel Application, Microsoft PowerPoint Slide). In this tab, each entry must be set to **This user** and used by the configured office user. - If any pop-ups are displayed, accept them and reconfigure, or run the following command in your CMD as administrator: ```shell configuration.office repair ``` ### 6. Office configuration validation 1. In your CMD, run the following command as administrator: ```shell configuration.office validate ``` 1. Optional: If the configuration was not valid, run the following command as administrator: ```shell configuration.office repair ``` ### 7. Manual PDF export 1. Optional: If you have chosen to create a new Office user automatically in the Configurator (`ConvsrvOfficeUser`), in your command-line interface (CMD), run the following command as administrator to get the Office user password: ```shell configuration.office -d ``` 1. Click the Windows start button, and search for either **Word**, **Excel**, or **PowerPoint**. 1. Right click, select **Run as different user**. 1. Use the name and the password of the Office user. 1. Check and accept activation pop-ups (especially in Excel). 1. Open the document manually and try **Save As** > **PDF** and **Print** > **Print to Pdf**. Use the same export settings as the Conversion Service. ### 8. Local user test If the Office user is a domain user, find out whether testing the installation with a local user is possible. Some policies may be only enforced for the domain user but not for a local user. ### 9. Additional troubleshooting steps - Use a manually created local user account instead of the one generated using the Configurator. - Grant local admin rights to the Office user and retest. - Test different server or Office combinations to isolate environment-specific issues. --- ## Configure conversion of redlined Microsoft Word documents Learn how to set up the Conversion Service to convert Microsoft Word documents with tracked changes (revisions, also called redlining) to PDF. **info: Track changes conversion is supported by both the [Standard Converter](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#standard-converter-default) and the [local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation). The Standard Converter enables this feature under **Standard Converter Settings** > **Word Settings** > **Track Changes (Redlining)**. The local Office installation uses the setting described on this page.** ## Introduction to track changes The track changes in Microsoft Word highlight modifications made to a document, enabling users to review, accept, or reject changes collaboratively. The **track changes to PDF (redlining)** lets you convert Microsoft Word files into fully archived PDFs that preserve all revisions, comments, and annotations made using the track changes feature. This conversion is designed for legal professionals, corporate legal teams, and IT providers. Key features can be listed as follows: - **Full revision history**: Retain a complete, transparent record of tracked changes for legal review. - **Secure archiving**: Convert documents to universally accessible, compliant PDF formats. - **Efficiency and accuracy**: Prevent data loss during conversion, streamlining legal and compliance workflows. - **Support legal use cases**: Enable regulatory compliance, audits, and legal reviews, with PDFs that preserve edits and annotations for universal compatibility. ## Enable conversion of redlined documents The steps to enable track changes conversion depend on which Office conversion method you use. The Standard Converter is enabled by default and exposes a separate setting from the local Microsoft Office installation. ### Standard Office conversion To enable track changes conversion with the [Standard Converter](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#standard-converter-default), follow these steps: 1. In the **Conversion Service Configurator**, go to the **Conversion Service** tab, and then find the **Standard Converter Settings** section. 1. Under **Word Settings**, enable the **Track Changes (Redlining)** toggle. 1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**. ### Local Microsoft Office conversion To enable track changes conversion with a [local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation), follow these steps: 1. In the Conversion Service Configurator, navigate to **Workflows and Profiles**, and then click the pen icon to edit the profile configuration. 1. In the Office Conversion section, enable **Track Changes (Redlining)** toggle. 1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**. ## Example of converted documents The following sections demonstrate the resulting PDFs after conversion. ### Initial Microsoft Word document The following image displays a Microsoft Word document with tracked changes before conversion: ### Converted PDF with track changes enabled After conversion, the PDF preserves all tracked changes (redlining): ### Resulting PDF with track changes disabled After conversion, the PDF does not preserve tracked changes (redlining): --- ## Get started with the Conversion Service The Conversion Service is a flexible document solution that lets you convert and optimize high volumes of documents with ease. Install the Conversion Service to get ready for your first conversion. Get started with one of the following getting started guides: --- ## Conversion Service APIs overview Learn about the Conversion Service APIs and how to use them. Integrate and automate complex file processing pipelines using a locally hosted API. The Conversion Service provides two APIs that you can use to automate documentation workflows and processes: - **[Simple API](#simple-api)**: Process files in one API call. Get started fast with the Simple API, designed to solve common use cases of the conversion process. - **[Advanced API](#advanced-api)**: Leverage fine-grained control over the conversion process, letting you convert many documents in bulk and check their status during the conversion process. Reliably process the harmonization of documents from various sources and prepare them optimally for your intended purpose. ### Simple API The examples of the Simple API use cases include the following: - Convert files with one API call. - Convert documents one by one with a blocking call until the API delivers the converted PDFs. - Implement the Conversion Service with multiple applications with a dedicated API for each application. Each application can include different Workflows and Profiles. - Convert large files (larger than 100 MB) using the plain HTTP input endpoint of the Simple API. Review the [Simple API](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/simple-api) getting started for more information. ### Advanced API The examples of Advanced API use cases include the following: - Merge hundreds of documents into a single PDF using the Create Dossier PDF workflow. - List and monitor all jobs processed, workflows, and profiles on your server. - Monitor the status of the Conversion Service to ensure that everything is running correctly. - Store the results of the conversion on an Amazon S3, Azure Blob Storage, SharePoint and choose the destination location on the fly. - Collect all the files over time and wait until all documents are ready to be converted. Create a job, add files over time, and then start the conversion job. - Convert large files (larger than 100 MB). Review the [Advanced API](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/advanced-api) getting started for more information. **info: If you already reviewed both getting started guides, learn more details about the Simple API and Advanced APIs on the [API references](https://www.pdf-tools.com/docs/conversion-service/api/) page.** --- ## Get started with Advanced API Learn how to integrate an API to reliably process the harmonization of documents from various sources and prepare them optimally for your intended purpose with a detailed configuration. Convert a file using the Advanced API Postman collection. ## Prerequisites To use the APIs explained in this documentation, fulfill the following prerequisites: - Finish the [Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server) or [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker) getting started guides. - Install [Postman](https://www.postman.com/downloads/) client. ## Convert a file Convert a file using the default configuration with a Postman collection: 1. Download the [Advanced API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_advanced_api.postman_collection.json). If this link only opens a new tab in your browser and doesn't start a file download, copy the JSON content from the tab in your browser into a file called `conversion_service_advanced_api.postman_collection.json` and save it. 1. In the Postman client, click **Import**, and then follow the steps described in the Postman client to import a collection. 1. Optional: If the Conversion Service Configurator is running on a different machine: 1. Specify its IP address in the **Conversion Service Simple API** folder > **Variables**. 1. Next to the `baseURL`, in the **Current value** column, change the value of the `localhost` to the IP address of the computer where the Conversion Service Configurator is running. 1. In the Postman collection, open the **Conversion Service Advanced API** > **Job Processing** > **Create new job**. 1. Optional: Change the Profile you want to use for the file conversion. To use the custom profile created in the previous guides, open the **Params** tab, and then in the **Value** field of the **profile** key use for example: **awesome-test-profile** 1. Click **Send**. 1. Open **Add data to job**, click **Body**, and then in the **Value** field of the **data** key, add the file you want to convert. 1. Click **Send**. 1. Open **Start job**, and then click **Send**. 1. Open **Get job info**, and then click **Send**. In the response, you receive the current status of the conversion processing. 1. Open **Get job result data**, and then click **Send**. In the response, you receive the converted file. Explore the Postman collection and see which parameters are being parsed and copied to calls of other endpoints, especially the `jobId`. With the Advanced API, you can also upload files for processing stored in a URL (**Add data by url to job** endpoint), send converted documents to a URL (**Store job result data** endpoint), create many jobs for processing at the same time, list statuses of all jobs, delete specific jobs. The Advanced API let's you implement the document processing workflow in great details. In short, to schedule a job and retrieve its result, the sequence is as follows: **info: To learn more about the Advanced API, review **[Integrate through Advanced API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api)** page and [Advanced API references](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/advanced-api).** --- ## Get started with Simple API Learn how to convert files using the Conversion Service Simple API. Process files in one API call. Convert documents individually with a blocking call until the API delivers the converted files. Implement the Conversion Service with multiple applications, each with a dedicated API. Each application can include different Workflows and Profiles. Convert large files (larger than 100 MB) using the plain HTTP input endpoint of the Simple API. The Conversion Service provides various predefined Simple API connectors. This getting started guide explains how to convert files using the **Archive PDF/A-2** connector. You can find the complete list of other connectors in the Integrations tab of the Conversion Service Configurator (review the following screenshot). Note that in the Conversion Service Configurator, all of these connectors include **REST API** in their name. However, this **REST API** wording is not included in the API references or in the Postman collection. For example: **Archive PDF/A-2** in the Postman collection or API references is **REST API Archive PDF/A-2** in the Conversion Service Configurator. ## Prerequisites To use the APIs explained in this documentation, fulfill the following prerequisites: - Finish the [Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server) or [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker) getting started guides. - Install [Postman](https://www.postman.com/downloads/) client. ### Additional Docker configuration When you finish the Docker getting started guide, you have a `docker-compose.yaml` file with a configuration similar to the following: ```yaml volumes: vol-conversion-srv-app-data: {} services: conversion-service: # Conversion Service image - Converts files to PDF format. image: pdftoolsag/conversion-service environment: # To activate the license, pass the value of the license key. LICENSEKEY: LICENSE_KEY_VALUE LICENSINGSERVICE: http://LGS_IP_ADDRESS:9999 IMPORT_PROFILES: /etc/convsrv/PROFILE_EXPORT_FILE SERVICE__OFFICE__TYPE: OfficeWebService SERVICE__OFFICE__USERNAME: YOUR_OFFICE_USERNAME ports: # Exposes port 13033 for external communication. - "13033:13033" volumes: - vol-conversion-srv-app-data:/etc/convsrv - HOST_PROFILE_DIR/PROFILE_EXPORT_FILE:/etc/convsrv/PROFILE_EXPORT_FILE ``` Replace the following: - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `LGS_IP_ADDRESS`: The IP address of the machine running the Licensing Gateway Service. Use `9999` as the recommended port. - `HOST_PROFILE_DIR`: The directory on the host machine that contains the exported profile (for example, `C:/Users/john-doe/Desktop`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). - `YOUR_OFFICE_USERNAME`: The Microsoft 365 account used for Office for the web conversion. To enable the Simple API, include additional code nested under the `services`: ```yaml connector-service: # Connector Service image: # Enables REST Input connectors, the REST input plain HTTP, and REST input JSON. image: pdftoolsag/connector-service ports: # Expose port 13034 for external communication. - "13034:13034" ``` ** **Click to expand for more information.** The complete example of the `docker-compose.yaml` with the added Connector Service:** ```yaml volumes: vol-conversion-srv-app-data: {} services: conversion-service: # Conversion Service image - Converts files to PDF format. image: pdftoolsag/conversion-service environment: # To activate the license, pass the value of the license key. LICENSEKEY: LICENSE_KEY_VALUE LICENSINGSERVICE: http://LGS_IP_ADDRESS:9999 IMPORT_PROFILES: /etc/convsrv/PROFILE_EXPORT_FILE SERVICE__OFFICE__TYPE: OfficeWebService SERVICE__OFFICE__USERNAME: YOUR_OFFICE_USERNAME ports: # Exposes port 13033 for external communication. - "13033:13033" volumes: - vol-conversion-srv-app-data:/etc/convsrv - HOST_PROFILE_DIR/PROFILE_EXPORT_FILE:/etc/convsrv/PROFILE_EXPORT_FILE connector-service: # Connector Service image: # Enables REST Input connectors, the REST input plain HTTP, and REST input JSON. image: pdftoolsag/connector-service ports: # Expose port 13034 for external communication. - "13034:13034" ``` Replace the following: - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `LGS_IP_ADDRESS`: The IP address of the machine running the Licensing Gateway Service. Use `9999` as the recommended port. - `HOST_PROFILE_DIR`: The directory on the host machine that contains the exported profile (for example, `C:/Users/john-doe/Desktop`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). - `YOUR_OFFICE_USERNAME`: The Microsoft 365 account used for Office for the web conversion. ## Convert file using default configuration Convert files to PDF/A-2 using the default Connection, Workflow, and Profile. There are two methods how you can call the Simple API using any Connection: - [REST input plain HTTP](#rest-input-plain-http): Provides support for converting large files (larger than 100 MB). - [REST input JSON](#rest-input-json): Provides structured input and output in Base64 encoded format. ### REST input plain HTTP To convert a file to PDF/A-2 using the REST input plain HTTP: 1. Download the [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json). If this link only opens a new tab in your browser and doesn't start a file download, copy the JSON content in your browser into a file called `conversion_service_simple_api.postman_collection.json` and save it. 1. In the Postman client, click **Import**, and then follow the steps described in the Postman client to import a collection. 1. Optional: If the Conversion Service Configurator is running on a different machine: 1. Specify its IP address in the **Conversion Service Simple API** folder > **Variables**. 1. Next to the `baseURL`, in the **Current value** column, change the value of the `localhost` to the IP address of the computer where the Conversion Service Configurator is running. 1. In the Postman collection, open the **Conversion Service Simple API** > **Archive PDF/A-2** > **REST input plain HTTP**. 1. Click **Body**, and then next to the `data` key, add the file you want to convert in the **Value** field. 1. Click **Send**. You receive a file converted to PDF/A-2 in response to this API call. ### REST input JSON To convert a file to PDF/A-2 using the REST input JSON: 1. Download the [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json). 1. In the Postman client, click **Import**, and then follow the steps described in the Postman client to import a collection. 1. Optional: If the Conversion Service Configurator is running on a different machine: 1. Specify its IP address in the **Conversion Service Simple API** folder > **Variables**. 1. Next to the `baseURL`, in the **Current value** column, change the value of the `localhost` to the IP address of the computer where the Conversion Service Configurator is running. 1. In the Postman collection, open the **Conversion Service Simple API** > **Archive PDF/A-2** > **REST Input JSON**. 1. Click **Body**, and then add your Base64 encoded file as a value of the `"content"` parameter. For example: ```json "content": "SGVsbG8gd29ybGQuCg==" ``` 1. Click **Send**. You receive the file converted to PDF/A-2 in Base64 encoded format in response to this API call. **info: The REST input JSON endpoint lets you also upload files using a URL that you can specify in the request body. For more details, review [REST input JSON API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json).** ## Convert file using custom configuration In the [Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server) or [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker) guides, we created a profile called an **awesome-test-profile** that adds a stamp to converted documents. Let's use it again while we also configure a custom Connection. :::info[Functionality unavailable in Docker] The following sections are not available for Docker users. Using a custom Connection is only available on Windows and Windows Server. You cannot add a custom Connection to a Docker instance of the Conversion Service. To workaround this limitation, change the preconfigured `archive-pdfa2-default` Connection configuration. You can change its Workflow and Profiles. ### Create custom Connection **Connection** is a special term in the Conversion Service. A Connection is a set of various input sources (called connectors) and outputs. The Simple API is one such input source (connector) that you can include in a Connection. To set up a new Connection with the following steps: 1. In the Conversion Service Configurator, click the **Integration** tab. 1. Click **Add**. 1. In the **Name** field, add a name to the new integration. For example: **get-started-integration** 1. In the **Processing** section, click the drop-down list next to **Workflow**, and then select **Archive PDF/A-2**. 1. Also, in the **Processing** section, click the drop-down list next to **Profile**, and then select for example: **awesome-test-profile** 1. In the **Input** section, click **Add**. 1. Select **REST Input (JSON)**, and then click **Next**. 1. Optional: Change the auto-generated connection ID. For example: **input-get-started** 1. Click the drop-down list next to **Response**, and then select **Result**. 1. Click **Apply**. 1. Again, in the **Input** section, click **Add**. 1. Select **REST Input (Plain HTTP)**, and then click **Next**. 1. Optional: Change the auto-generated connection ID. For example: **input-get-started** 1. Click the drop-down list next to **Response**, and then select **ResultFirst**. 1. Click **Apply**. 1. Click **Apply** again. 1. In the **Changes detected** dialog box, click **Save & Restart Service**. Let's convert files in the following sections using the custom Connection and Profile. ### REST input plain HTTP To convert a file using custom Connection and Profile, follow these steps: 1. In the Postman client, go to **Conversion Service Simple API**, and then click **Variables**. 1. Change the **Current value** of the **connectionID** to the connection ID you added to both the REST input JSON and REST Input HTML in the Configurator. For example: `input-get-started` 1. Optional: If the Conversion Service Configurator is running on a different machine: 1. Specify its IP address in the **Conversion Service Simple API** folder > **Variables**. 1. Next to the `baseURL`, in the **Current value** column, change the value of the `localhost` to the IP address of the computer where the Conversion Service Configurator is running. 1. In the Postman collection, open the **Conversion Service Simple API** > **Archive PDF/A-2** > **REST input plain HTTP**. 1. Click **Body**, and then next to the `data` key, add the file you want to convert in the **Value** field. 1. Click **Send**. In response to this API call, you receive a file converted to PDF/A-2 using your custom configuration. **tip: To use a custom Connection, change the **connectionID** in the Postman collection to the value of the connection ID defined in the Conversion Service Configurator. The pre-configured value of the connection ID is `archive-pdfa2-default`.** ### REST input JSON To convert a file using custom Connection and Profile, follow these steps: 1. In the Postman client, go to **Conversion Service Simple API**, and then click **Variables**. 1. Change the **Current value** of the **connectionID** to the connection ID you added to both the REST input JSON and REST Input HTML in the Configurator. For example: `input-get-started` 1. Optional: If the Conversion Service Configurator is running on a different machine: 1. Specify its IP address in the **Conversion Service Simple API** folder > **Variables**. 1. Next to the `baseURL`, in the **Current value** column, change the value of the `localhost` to the IP address of the computer where the Conversion Service Configurator is running. 1. In the Postman collection, open the **Conversion Service Simple API** > **Archive PDF/A-2** > **REST input JSON**. 1. Click **Body**, and then add your Base64 encoded file as a value of the `"content"` parameter. For example: ```json "content": "SGVsbG8gd29ybGQuCg==" ``` 1. Click **Send**. You receive the file converted to PDF/A-2 in Base64 encoded format using your custom configuration in response to this API call. **tip: To use a custom Connection, change the **connectionID** in the Postman collection to the value of the connection ID defined in the Conversion Service Configurator. The pre-configured value of the connection ID is `archive-pdfa2-default`.** **info: The REST input JSON endpoint lets you also upload files using a URL that you can specify in the request body. For more details, review [REST input JSON API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/rest-input-json).** ## API references Get more details about the Simple API. Review the API references on the [Simple API](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api) references page. --- ## Conversion Service in Docker Learn how to run the Conversion Service in Docker. ## Get trial license To try or fully use the Conversion Service, you must obtain a license key. To get the Conversion Service evaluation license key for free, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service Trial**, click the **Copy **. You now have a free trial license key. Its limitations are the following: - The converted files have a watermark - The license key is limited to 90 days. **note: The trial license key is valid for 90 days starting at UTC time. The Pdftools Portal indicates the validity period starting at 89 days (as the consumption of the first day already started). This period may slightly vary depending on your time zone relative to UTC.** ## Request full license **tip: You can try the Conversion Service for free with a trial license key. In this section, you can learn how to request a full license key.** To request a full license key, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Request license**. 1. On the **Contact us** window, fill in the requested fields, and then click **Submit**. ## Prerequisites The following sections use examples running with Docker Compose: - You have **Docker Compose** installed to run the Conversion Service in Docker. - You have a Windows Server or Windows machine to export configuration files. **info: Installing Conversion Service on Windows 10 or 11 is possible, although we recommend using it only to export the configuration files. Pdftools provides official support for the Conversion Service for the Windows Server or Docker containers listed in the [Compatible operating systems](https://www.pdf-tools.com/docs/conversion-service/#compatible-operating-systems). If you run the Conversion Service on Windows 10 or Windows 11 for production purposes, you may not receive our full support.** ## Install Conversion Service on Windows :::tip[Windows installation prerequisites] For the Conversion Service on Windows or Windows Server machine, you need the following dependencies installed: - [.NET Desktop Runtime 8.0+ (x64)](https://aka.ms/dotnet-core-applaunch?framework=Microsoft.AspNetCore.App.Desktop&framework_version=8.0.0&arch=x64&rid=win-x64&os=win10&gui=true) - [ASP.NET Core Runtime 8.0+ (x64)](https://aka.ms/dotnet-core-applaunch?framework=Microsoft.AspNetCore.App&framework_version=8.0.0&arch=x64&rid=win-x64&os=win10&gui=true) Install the Conversion Service on Windows Server or Windows 10 or 11 so you can export configuration files to your Docker instance with the following steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. In the **Product builds** section, find the `conversion-service-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `conversion-service-6.10.0.msi`, depends on the version you are installing. Ensure to download `conversion-service-VERSION_NUMBER.msi` **not** `conversion-service-client-VERSION_NUMBER.msi` due to the focus of this guide. 1. Open the `conversion-service-VERSION_NUMBER.msi` installer and proceed with the guided installation.**[^1]** 1. In the [Pdftools Portal](https://portal.pdf-tools.com/), on the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service** license key, click **Click to copy**. 1. Open **Conversion Service Configurator**, and then click the **License** tab. 1. Paste the license key into the **Key** field and click **Add**. ### Installation details The `conversion-service-VERSION_NUMBER.msi` installs the Conversion Service itself and provides the following applications that let you configure workflow profiles and more: - Conversion Service Configurator - PDF Client for Conversion Service - Conversion Service shell client (CLI) - Licensing Gateway Service ## Run Conversion Service in Docker To run the Conversion Service in a Docker container, follow these steps: 1. Create a file named `docker-compose.yaml` and insert the following code: ```yaml services: conversion-service: # Conversion Service image. Converts files to PDF format. image: pdftoolsag/conversion-service:IMAGE_VERSION environment: # To activate the Conversion Service, pass the value of the license key. LICENSEKEY: LICENSE_KEY_VALUE LICENSINGSERVICE: http://LGS_IP_ADDRESS:9999 ports: # Exposes port 13033 for external communication. - "13033:13033" ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number. For example: `6.0.0`, `6.0`, `6` - `LICENSE_KEY_VALUE`: Pass the license key value. - `LGS_IP_ADDRESS`: The IP address of the machine with the Licensing Gateway Service (LGS). The LGS is installed as part of the Conversion Service installer and can also be installed separately. Use `9999` as the recommended port address. 1. Optional: If you run the Conversion Service Docker instance within a machine where you also run the Conversion Service (for Windows or Windows Server), you need to free up one of the used ports. Go to the **Conversion Service Configurator**, open the **Conversion Service** tab and then click **Stop**. This action frees port 13033 for the Docker instance. 1. In the directory where you created the `docker-compose.yaml`, run the following command: ```bash docker compose up -d ``` :::tip[Set up licensing differently] The `LICENSINGSERVICE` parameter configures the Licensing Gateway Service (LGS) endpoint. The LGS sends your hostname and the number of processed pages (license usage data). No other data about the documents you processed is sent. In the demonstrated configuration, the Windows machine sends usage data of your Docker container. You can install and configure the LGS in a Docker container or any other machine and let it send license usage data for an unlimited number of Conversion Service instances with just one license key. For more details about the LGS, review the following pages: - [Conversion Service licensing](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/). - [Set up the Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) ## Convert file Learn how to convert files using the Conversion Service Docker instance through the PDF Client for Conversion Service. Convert a PDF file to PDF/A using the default configuration: 1. In the **PDF Client for Conversion Service**, drag a PDF file to the **Input** box. 1. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the **vertical three-dot menu**, click **Settings**, add the IP address of your Docker instance, and then click **Apply**. 1. In the **Profile** drop-down list, select the **Default** profile. 1. Click **Convert**. **info: In the PDF Client for Conversion Service, you can select various workflows and profiles to choose specific conversion types. You can also change the filename of the output file.** ## Configure and export a profile Configure a custom profile to add a QR code to converted documents and export the configuration to your Docker container: 1. In your Windows machine, open the **Conversion Service Configurator**, go to **Workflows & Profiles**. 1. Next to **Archive PDF/A-2**, click **Add**. 1. Create a name for the new profile. For example: **awesome-test-profile** 1. In the **Processing Steps** section, enable the **Stamp and Annotation** toggle. 1. Scroll down to the **Stamp and Annotation** section, and then click **Add item**. 1. Click **Barcode Stamp**, and then click **Next**. 1. In the **Type** field, select **QR**. 1. In the **Value** field, enter any text you like (it can be a website link). For example: **Hello world** 1. Scroll down to the **Layout** section, and set the **Width** and **Height**. For example, set it to 3 cm. 1. Optional: To display the stamp in the top left corner of the PDF file, edit other parameters in the **Layout** section as follows: If you don't specify any values in the **Layout** section, the QR code is displayed in the center of the page. 1. Click **Apply**, then click **Apply** in the Configurator again. 1. In the **Changes detected** dialog box, click **Save & Restart Service**. 1. In the **Workflows & Profiles** page, click the **vertical three dots menu**, and then click **Export Profiles**. 1. Select the name of the profile you want to export, for example: **awesome-test-profile**, or click **Select All** to export all profiles. 1. Click **Export**, and then select the file destination. 1. Edit the `docker-compose.yaml` to mount the configuration file from your Windows machine: ```yaml services: conversion-service: # Conversion Service image. Converts files to PDF format. image: pdftoolsag/conversion-service:IMAGE_VERSION environment: # To activate the Conversion Service, pass the value of the license key. LICENSEKEY: LICENSE_KEY_VALUE LICENSINGSERVICE: http://LGS_IP_ADDRESS:9999 IMPORT_PROFILES: /etc/convsrv/PROFILE_EXPORT_FILE ports: # Exposes port 13033 for external communication. - "13033:13033" volumes: - HOST_PROFILE_DIR/PROFILE_EXPORT_FILE:/etc/convsrv/PROFILE_EXPORT_FILE ``` Replace the following: - `IMAGE_VERSION`: The Conversion Service version number (for example, `6.11.0`, `6.11`, or `6`). - `LICENSE_KEY_VALUE`: The Conversion Service license key. - `LGS_IP_ADDRESS`: The IP address of the machine running the Licensing Gateway Service. The Licensing Gateway Service is installed as part of the Conversion Service installer and can also be installed separately. Use `9999` as the recommended port. - `HOST_PROFILE_DIR`: The directory on the host machine that contains the exported profile (for example, `C:/Users/john-doe/Desktop`). - `PROFILE_EXPORT_FILE`: The filename of the exported profile (for example, `ProfileExport-6.11.0.export`). 1. In the directory where you created the `docker-compose.yaml`, run the following command: ```bash docker compose up ``` :::info[Available fonts] If you use **text stamp** or **text annotation** rather than the demonstrated QR code, ensure to install the selected font family in the Docker container. For example, the Configurator selects Calibri fonts for text stamps by default, but you must install the Calibri font family to finish the processing successfully. ## Convert file using custom profile Learn how to apply a profile created in the section [Configure and export a profile](#configure-and-export-a-profile). Convert a PDF file to PDF/A using your custom profile configuration: 1. In the **PDF Client for Conversion Service**, drag a PDF file to the **Input** box. 1. In the **Profile** drop-down list, select a created custom profile. For example: **awesome-test-profile** 1. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the **vertical three-dot menu**, click **Settings**, add the IP address of your Docker instance, and then click **Apply**. 1. Click **Convert**. ## Microsoft Office file conversion The Conversion Service converts Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files to PDF out of the box using the [Standard Converter](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#standard-converter-default). No additional configuration is required for fresh installations, and the Docker image ships with metric-compatible fonts (Carlito, Caladea, Liberation, Noto, DejaVu, and Microsoft core fonts) so that documents retain their original layout. To convert a Microsoft Office file: 1. In the **PDF Client for Conversion Service**, drag a Microsoft Office file to the **Input** box. 1. In the **Profile** drop-down list, select a profile with Office conversion enabled. Most profiles have this option enabled by default. 1. Optional: If you are running the Docker instance on a machine other than the one where you installed Conversion Service on Windows, click the **vertical three-dot menu**, click **Settings**, add the IP address of your Docker instance, and then click **Apply**. 1. Click **Convert**. If you need pixel-perfect layout preservation, password-protected files, or the legacy binary formats DOC, PPT, and PPS, configure the [Office for the web service](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#office-for-the-web-service) or delegate Office jobs to a Conversion Service instance running on Windows with a [local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation). To add corporate or proprietary fonts to the container, see [Add custom fonts](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#add-custom-fonts). **note: If you experience any issues during configuration or conversion, refer to the [Troubleshooting](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting) in the Convert Microsoft Office files documentation.** ## Next steps For more details about Docker configuration, see [Set up the service in Docker](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container) page. You learned how to run the Conversion Service in Docker, convert a file using default profile, create a custom profile, export it, and convert a file using custom profile. Review the following documentation for more details: - [Set up the service depending on your installation](https://www.pdf-tools.com/docs/conversion-service/configure/). - Adapt the default profile or [create a new profile for a workflow](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). - [Create a new workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/) There are several ways you can [integrate the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/integrate/) into your system: - [Shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) - [REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api) ### Use PDF/A-2 instead of PDF/A-1 in Docker The PDF/A-2 is based on a newer version of the PDF standard than PDF/A-1, more PDF features are allowed such as transparency, layers, embedded files, and a less restrictive internal file structure. For these reasons, achieve fewer conversion errors and better conversion quality with the Archive as PDF/A-2 workflow. Particularly, if you use the Conversion Service in a Docker container where document content rasterization is unavailable, use PDF/A-2 workflow instead to avoid visual differences, removed transparency, or other potential issues. For more information, review [Features and limitations](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1#features-and-limitations). [^1]: During the installation on the Windows Server or Windows machine, the installer automatically prompts you to install the following dependencies: - [.NET Desktop Runtime 8.0+ (x64)](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-8.0.13-windows-x64-installer?cid=getdotnetcore) - [ASP.NET Core Runtime 8.0+ (x64)](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-8.0.13-windows-x64-installer?cid=getdotnetcore) --- ## Conversion Service on IONOS Cloud Learn how to deploy Conversion Service on IONOS Cloud using either a Windows virtual machine or Managed Kubernetes. IONOS is a European cloud provider offering public, private, and hybrid cloud services. ## Get a license To use the Conversion Service, you need a license key. You can get a free trial license or request a full license from the Pdftools Portal. For detailed instructions, review [Get trial license](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#get-trial-license). ## Prerequisites Before deploying Conversion Service on IONOS Cloud, make sure you have: - An [IONOS Cloud account](https://cloud.ionos.com/) - A valid Conversion Service license key ## Deployment options Choose one of the following deployment methods based on your requirements: - **Windows virtual machine**: MSI (Microsoft Installer) based installations, full Configurator access, Microsoft Office conversion. For more details, review [Create Windows VM](#create-windows-vm). - **Managed Kubernetes**: Containerized workloads, scalable deployments, microservices architectures. For more details, review [Create Kubernetes cluster](#create-kubernetes-cluster). ## Create Windows VM Deploy the Conversion Service with an MSI-based installation on a Windows Virtual Machine. 1. Log in to the [IONOS Data Center Designer (DCD)](https://dcd.ionos.com/). 1. Create a new data center or select an existing one. 1. Drag a **Dedicated Core** server into your data center and configure the server specifications. For sizing guidance, review [hardware requirements](https://www.pdf-tools.com/docs/conversion-service/#hardware-requirements). - **CPU**: Select the number of cores. - **RAM**: Allocate memory. - **Architecture**: Select the CPU architecture. 1. Add storage to your server: - Attach a storage volume. - Select a **Windows Server** image as the boot image. 1. Set the **Administrator password** for your VM. You use this password to connect through Remote Desktop Protocol (RDP). 1. Click **Provision changes** to create your infrastructure. 1. Once provisioning completes, navigate to the **Network** tab of your server to find the public IP address. ### Connect and install 1. Use Remote Desktop Protocol (RDP) to connect to your VM using the public IP address and Administrator credentials. 1. Follow the standard [Windows Server installation guide](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server) to install and configure the Conversion Service. :::tip[Official IONOS documentation] For detailed instructions on creating Windows virtual machines, refer to the [IONOS Dedicated Core Server guide](https://docs.ionos.com/cloud/compute-services/compute-engine/how-tos/set-up-dedicated-core). ## Create Kubernetes cluster Deploy the Conversion Service as a container on IONOS Managed Kubernetes for containerized deployment. 1. Log in to the [IONOS Data Center Designer (DCD)](https://dcd.ionos.com/). 1. Navigate to **Containers** > **Managed Kubernetes**. 1. Click **Create Cluster** and configure the cluster settings: - **Cluster name**: Enter a descriptive name. - **Kubernetes version**: Select the desired version. - **Location**: Choose a data center location. 1. Create a **Node Pool** and configure the node specifications. For sizing guidance, review [hardware requirements](https://www.pdf-tools.com/docs/conversion-service/#hardware-requirements). - **Node count**: Start with at least one node. - **CPU and RAM**: Select based on your workload. - **Storage**: Allocate enough storage for your containers. 1. Wait for the cluster and nodes to reach the **Active** state. 1. Download the **kubeconfig.yaml** file from the cluster details page. ### Deploy the Conversion Service 1. Set the `KUBECONFIG` environment variable to point to your downloaded kubeconfig file: ```bash export KUBECONFIG="./kubeconfig.yaml" ``` 1. Deploy the Conversion Service container by following the [Docker getting started guide](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker). The same container image and configuration options apply to Kubernetes deployments. 1. Verify the deployment status: ```bash kubectl get pods kubectl get services ``` :::tip[Official IONOS documentation] For detailed instructions on managing Kubernetes clusters, refer to the [IONOS Managed Kubernetes guide](https://docs.ionos.com/cloud/containers/managed-kubernetes/how-tos/cluster_management). ## Next steps After deploying the Conversion Service on IONOS Cloud: - [Configure the service](https://www.pdf-tools.com/docs/conversion-service/configure/) based on your deployment type. - [Create custom profiles](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) for your conversion workflows. - [Integrate the service](https://www.pdf-tools.com/docs/conversion-service/integrate/) with your applications using the REST API or shell client. --- ## Conversion Service on Windows Server Learn how to install and use the Conversion Service on Windows Server to automate document processes. ## Get trial license To try or fully use the Conversion Service, you must obtain a license key. To get the Conversion Service evaluation license key for free, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service Trial**, click the **Copy **. You now have a free trial license key. Its limitations are the following: - The converted files have a watermark - The license key is limited to 90 days. **note: The trial license key is valid for 90 days starting at UTC time. The Pdftools Portal indicates the validity period starting at 89 days (as the consumption of the first day already started). This period may slightly vary depending on your time zone relative to UTC.** ## Request full license **tip: You can try the Conversion Service for free with a trial license key. In this section, you can learn how to request a full license key.** To request a full license key, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Request license**. 1. On the **Contact us** window, fill in the requested fields, and then click **Submit**. ## Prerequisites You need a Windows Server machine with the following dependencies installed: - [.NET Desktop Runtime 8.0+ (x64)](https://aka.ms/dotnet-core-applaunch?framework=Microsoft.AspNetCore.App.Desktop&framework_version=8.0.0&arch=x64&rid=win-x64&os=win10&gui=true) - [ASP.NET Core Runtime 8.0+ (x64)](https://aka.ms/dotnet-core-applaunch?framework=Microsoft.AspNetCore.App&framework_version=8.0.0&arch=x64&rid=win-x64&os=win10&gui=true) ## Download the installer To download the Conversion Service installer, follow these steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. In the **Product builds** section, find the `conversion-service-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `conversion-service-6.10.0.msi`, depends on the version you install. Available installers explained: - **Windows Server**: The `conversion-service-VERSION_NUMBER.msi` installs the Conversion Service itself and provides the following applications that let you configure workflow profiles and more: - Conversion Service Configurator - PDF Client for Conversion Service - Conversion Service shell client (CLI) - Licensing Gateway Service (LGS) - **Windows** clients: `conversion-service-client-VERSION_NUMBER.msi` to install the following applications: - PDF Client for Conversion Service - Conversion Service shell client (CLI) - Office Add-ins **caution: Don't install the `conversion-service-client-VERSION_NUMBER.msi` installer on the same machine where you installed the Conversion Service Configurator with the `conversion-service-VERSION_NUMBER.msi`. Conflicting installations can cause the Conversion Service to stop functioning correctly.** ## Install Conversion Service and activate the license key To install the Conversion Service and activate the license key, follow these steps: 1. Open the `conversion-service-VERSION_NUMBER.msi` installer and proceed with the guided installation. 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service Trial** or **Active**, click the **Copy **. 1. Open **Conversion Service Configurator**, and then click the **License** tab. 1. Paste the license key into the **Key** field and click **Add**. ## Basics of the Conversion Service The following sections guide you through the essentials of the Conversion Service. Follow each of these sections step by step: 1. [Convert a file](#convert-a-file) 1. [Configure a profile](#configure-a-profile) 1. [Configure Microsoft Office file conversion](#configure-microsoft-office-file-conversion) 1. [Configure a watched folder](#watched-folder) 1. [Convert various files](#convert-various-files) ### Convert a file Convert a PDF file to PDF/A using the default configuration: 1. In the **PDF Client for Conversion Service**, drag a PDF file to the **Input** box. 1. Click **Convert**. **info: In the PDF Client for Conversion Service, you can select workflows and profiles to specify conversion types and change the output filename.** Alternatively, you can also use a shell client to make the same conversion using the default profile: 1. In a command prompt, issue the following command: ```shell pdfclient input.pdf output.pdf ``` The `input.pdf` file is located on your machine, and `output.pdf` is the name of the generated PDF. The output file is saved in the same directory where you are currently working with the shell client. :::tip[Log files] You can find the data about your successful conversion in log files. The Conversion Service saves these files by default in the `C:\ProgramData\Pdftools\Conversion Service\Logs` folder. The Conversion Service uses different log files: - `ConversionService-Service.log`: Main service log file (current). - `ConversionService-Service-DATE.log`: Past service logs. - `ConversionService-Connections.log`: For any [Connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/) services, such as Watched Folder, email connectors, or REST connectors. - `ConversionService-Configurator.log`: For the Conversion Service Configurator application. For more information, review [Service log](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log) documentation. ### Configure a profile Configure a custom profile to add a stamp to converted documents: 1. In the **Conversion Service Configurator**, go to **Workflows & Profiles**. 1. Next to **Archive PDF/A-2**, click **Add**. 1. Create a name for the new profile. For example: **awesome-test-profile** 1. In the **Processing Steps** section, enable the **Stamp and Annotation** toggle. 1. Scroll down to the **Stamp and Annotation** section, and then click **Add item**. 1. Click **Text Stamp**, and then click **Next**. 1. In the **Text** field, enter a stamp text. For example: **Hello world** 1. Optional: To display the stamp in the top left corner of the PDF file, find the **Layout** section, and edit the parameters as follows: If you don't specify any values in the **Layout** section, the stamp is displayed in the center of the page. 1. Click **Apply**, then click **Apply** in the Configurator again. 1. In the **Changes detected** dialog box, click **Save & Restart Service**. 1. In the **PDF Client for Conversion Service**, drag a PDF file to the **Input** box. 1. In the **Profile** drop-down list, select a created custom profile. For example: **awesome-test-profile** 1. Click **Convert**. :::info[Available fonts] Install the fonts you selected for the **text stamp** or **text annotation** on your server machine. For example, the Configurator selects Calibri fonts for text stamps by default, but you must install the Calibri font family to finish the processing successfully. You learned to configure your custom profile for Archive as PDF/A-2 workflow, and add a configured stamp on converted documents. ### Configure Microsoft Office file conversion The Conversion Service converts Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files to PDF out of the box using the [Standard Converter](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#standard-converter-default). No additional configuration is required for fresh installations. To convert a Microsoft Office file: 1. In the **PDF Client for Conversion Service**, click the **Profile** drop-down list, and then select a profile that uses Office conversion. For example, **awesome-test-profile**. 1. Drag a Microsoft Office file to the **Input** box. 1. Click **Convert**. If you need pixel-perfect layout preservation, support for password-protected files, or legacy binary formats (DOC, PPT, PPS), configure a local Microsoft Office installation or the Office for the web service. For setup steps and licensing requirements, see [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). **note: If you experience any issues during configuration or conversion, refer to the [Troubleshooting](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting) in the Convert Microsoft Office files documentation.** ### Watched folder A watched folder automatically processes files placed into it. When you drop files into a watched folder, the Conversion Service detects them, processes them according to your configured workflow and profile settings, and then outputs the converted files to a designated location. #### Configure a watched folder Automatically convert all documents every time you add a file to the specified folder called a watched folder. To integrate a watched folder, follow these steps: 1. In the **Conversion Service Configurator**, go to **Integration**, and then click **Add**. 1. Name the integration. For example: **custom-watched-folder**. 1. Select **Archive PDF/A-2** as a workflow, and then select a profile. You can use the profile created earlier in this getting started guide. For example: **awesome-test-profile** 1. Click **Input**, and then select the **Watched Folder** and click **Next**. 1. Select an input folder path, and then click **Apply**. 1. Click **Output**, and then select the **Output Folder** and click **Next**. 1. Select the output folder path, and then click **Apply**. 1. Click **Apply** again. 1. In the **Changes detected** dialog box, click **Save & Restart Service**. When you include PDF files in the watched folder, the Conversion Service automatically converts them using the selected workflow and profile and copies them to the output folder. In this case, the **awesome-test-profile** example added a stamp and converted PDF files to PDF/A-2. ### Convert various files The Conversion Service converts as many file formats as possible into selected output formats. Use it to convert various files: 1. In the **PDF Client for Conversion Service**, drop various files to the **Drag & drop files and folders here or click to select files** section. For example: - PNG image - JPEG image - An EML (email message file) - A PDF file - An XML file 1. Optional: Enable the **Merge** toggle to merge all converted files into one. 1. Click **Convert**. If you enabled the **Merge** toggle, the Conversion Service created a PDF/A-2 with all the files nested as **the portfolio files**. ## Optional: Install and configure additional clients After installing the Conversion Service on a Windows Server machine, you can install additional clients on other Windows machines in your network. In this configuration, users in your network send files for processing to the Conversion Service running on your server. The files are automatically processed and sent back to the client machines. **info: Note that the `conversion-service-VERSION_NUMBER.msi` you installed in the previous section already includes the PDF Client for Conversion Service, which you can run on your server machine. Here you can learn how to install and run a client on other machines connected to your server.** 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. In the **Product builds** section, find the `conversion-service-client-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `conversion-service-client-6.10.0.msi`, depends on the version you are installing. 1. Connect the clients to your Conversion Service running on a server: 1. In the PDF Client for Conversion Service, click the three vertical dots , and then **Settings**. 1. In the **Service Host Address** field, insert the IP address or name of the server machine that hosts the Conversion Service. For more configuration options for this client, review [PDF Client for Conversion Service](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client) documentation. ## Next steps You learned how to run the Conversion Service on Windows Server, create and export a custom profile, and convert a file using PDF Client for Conversion Service. Review the following documentation for more details: - [Set up the service depending on your installation](https://www.pdf-tools.com/docs/conversion-service/configure/). - Adapt the default profile or [create a new profile for a workflow](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). - [Create a new workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/) You can also use several ways to [integrate the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/integrate/) into your system: - [Watched folder and other connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/) - [Shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) - [REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api) - [GUI](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client) --- ## Integrate the Conversion Service The Conversion Service can be integrated into your system using multiple interfaces depending on your specific requirements. There are several ways you can integrate the service, depending on your installation: **Windows:** - **[Shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client)**: Recommended for integration using scripts. Suited for automated and manually triggered processing. - **[REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api)**: Web service interface. Recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application. - **[Watched folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors)** connector: Converts documents copied from a pre-configured input folder to a pre-configured output folder. Recommended for file-share architecture integration. Suited for interactive and manual processing. - **[REST connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/)** Web service interface. A simpler REST interface recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application. - **[Watched mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** connector: Converts emails sent to a pre-configured mailbox to a pre-configured output folder. Recommended for integrating with IMAP or Exchange mail protocols. Suited for interactive and manually triggered processing. - **[PDF client](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client)**: Easy-to-use graphical user interface. Recommended for testing and familiarizing yourself with the Conversion Service. Suited for manually triggered processing only. - **[Plugins](https://www.pdf-tools.com/docs/conversion-service/configure/configure-plugins)**: Plugins are non-standard components used for extending the Conversion Service with custom workflows. - **Office Add-in**: Simple way for converting documents directly from an Office Application. A Conversion Service button is added to the toolbar, through which the conversion can be started immediately. ### Install the client The `conversion-service-client.msi` offers a standalone installation for the client applications. For automated installations, the `SERVICE_URL` property can be used to preconfigure the service URL of the Conversion Service. ``` msiexec /i conversion-service-client.msi SERVICE_URL=http://localhost:13033/conversion/v1.0/rest ``` The installation of the Office Add-in can be disabled in the installer. Office Add-ins are enabled in the `conversion-service-client.msi`. This adds a Conversion Service button to Microsoft Word, Outlook, Excel, and PowerPoint application toolbars. **Docker:** - **[Shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client)**: Recommended for integration using scripts. Suited for automated and manually triggered processing. - **[REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api)**: Web service interface. Recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application. - **[Watched folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors)** connector: Converts documents copied from a pre-configured input folder to a pre-configured output folder. Recommended for file-share architecture integration. Suited for interactive and manual processing. - **[REST connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/)** Web service interface. A simpler REST interface recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application. - **[Watched mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** connector: Converts emails sent to a pre-configured mailbox to a pre-configured output folder. Recommended for integrating with IMAP or Exchange mail protocols. Suited for interactive and manually triggered processing. **tip: To integrate with an existing system processes, you can [configure your Conversion Service](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections) to use [connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/) to process multiple files. ** --- ## Connectors The Conversion Service can be integrated into an existing system by combining suitable input and output connectors. You [configure your system](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections) to use connectors using the Conversion Service Configurator. There are two types of connector: - **Input connectors**: Used to receive or fetch conversion jobs from various sources. - **Output connectors**: Used to feed the converted file or files back into an existing system. The Conversion Service offers these connectors: ## Folder connectors - **[Watched folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder)**: Converts all files that are placed into a configurable input directory. After the conversion is finished, the files are deleted. - **[Output folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder)**: Copies files into a configurable output directory. - **[Create text file](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#create-text-file)**: Creates a text file in a configurable directory. ## Email connectors - **Watched mailbox** ([IMAP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-imap) or [Exchange Online](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-exchange-online)): Convert all emails that are placed into a configurable mailbox. After the conversion is finished, the mails are deleted. - **Output mailbox** ([IMAP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-imap) or [Exchange Online](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-exchange-online)): Copies files to a configurable mailbox. - **Send email** ([SMTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-smtp) or [Exchange Online](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-exchange-online)): Sends an email to a configurable recipient. ## REST connectors - **REST input** ([Plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http) or [JSON](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-json)): Converts all files that are sent to a URL. The URL can be customizable by setting the connection ID during configuration. - **[REST output](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-output-connectors)**: Posts files as a multipart/form-data request to a configurable output URL ## Other connectors - **[Execute command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command)**: Performs a configurable command on files. --- ## Email connectors Learn how to automatically convert all email messages received in inboxes you define and send and store the results to email addresses you select using the Conversion Service Email connectors. --- ## Docker Email connectors To use email connectors in Docker: 1. Configure your connections and import the `Connections.xml` file as described in [Configure connectors in Docker](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections#configure-connectors-in-docker). 1. Configure credentials for your email connectors as described in the following sections. :::warning[Concurrency] Use one connector service instance per email connection. Email protocols are not concurrency-safe and multiple instances monitoring the same mailbox may process emails multiple times. ## IMAP, SMTP, or Gmail Connectors Set the password using an environment variable on the connector service container: - **Environment variable**: `MAIL_` - **Example**: For `john.doe@gmail.com`, set `MAIL_JOHNDOEGMAILCOM` - **Value**: The Password ## Exchange Connectors Initialize the Exchange Online authentication by running: ```bash docker exec CONTAINER_ID_OR_NAME ./csconfig mail exchange-init ``` This command initiates the OAuth flow and generates a token, which is stored in `/etc/connsrv/TokenCaches`. **Persistent storage**: Mount a volume to preserve tokens across container restarts: ```yaml volumes: - ./token-caches:/etc/connsrv/TokenCaches ``` Without persistent storage, you must re-run `exchange-init` after each container restart. --- ## Windows Email connectors The email connectors include input and output connectors: - The **Watched Mailbox** connectors convert all emails that are placed into a configurable mailbox. After the conversion is finished, the mails are deleted. - The **Output Mailbox** connectors copy the files to a configurable mailbox. - The **Send Email** connectors are used to send an email to a configurable recipient. ## Watched Mailbox (IMAP) The Watched Mailbox (IMAP) connector converts all emails that are placed into a configurable mailbox on an IMAP server. After the conversion is finished, the mails are deleted. ### Settings - **Host/Port**: Host name and port of the IMAP server. - **SSL**: Type of encryption for connecting with the IMAP server. - **Username** and **Password**: Credentials for authenticating with the mail account. - **Mailbox Path**: Path where all incoming message are to be converted. - **Attachments only**: Turn on to process attached files only, and not the entire email body. - **Attach Skip Pattern**: Specify attachments of an email that are skipped by the Conversion Service. Use glob patterns such as the `*` and `?`. When you enable this option, the connector ignores attachments that match the specified patterns. - **Expression**: Enter valid glob patterns separated by semicolons. Patterns can include wildcards such as `*` and `?` to match multiple or single characters. - **Examples**: - `*.exe` - Skip all attachments with the `.exe` extension. - `*.jpg` - Skip all `.jpg` image attachments. - `invoice?.pdf` - Skip attachments like `invoice1.pdf`, `invoiceA.pdf`, etc. - `*report.docx` - Skip attachments like `myreport.docx`, `yourreport.docx`, etc. - `*.exe;*.jpg;invoice?.pdf;*report.docx` - Skip attachments matching any of these patterns. ### Variables The following variables are set by this input connector: - `From`: The sender of the email, including the display name if available. Examples: - `John Doe ` - `john.doe@example.com` - `Subject`: The subject of the email. ## Watched Mailbox (Exchange Online) This connector converts all emails that are placed into a configurable mailbox on a Microsoft Exchange Online server. After the conversion is finished, the mails are deleted. When selecting a mailbox, the connector asks for access to the emails on the specified account. The user must consent to this, otherwise the connector does not work. ### Settings - **Username**: Credentials to authenticate with the server. - **Mailbox Path**: Path where all incoming message are to be converted. - **Attachments only**: Turn on to process attached files only, and not the entire email body. - **Attach Skip Pattern**: Specify attachments of an email that are skipped by the Conversion Service. Use glob patterns such as the `*` and `?`. When you enable this option, the connector ignores attachments that match the specified patterns. - **Expression**: Enter valid glob patterns separated by semicolons. Patterns can include wildcards such as `*` and `?` to match multiple or single characters. - **Examples**: - `*.exe` - Skip all attachments with the `.exe` extension. - `*.jpg` - Skip all `.jpg` image attachments. - `invoice?.pdf` - Skip attachments like `invoice1.pdf`, `invoiceA.pdf`, etc. - `*report.docx` - Skip attachments like `myreport.docx`, `yourreport.docx`, etc. - `*.exe;*.jpg;invoice?.pdf;*report.docx` - Skip attachments matching any of these patterns. ### Variables The following variables are set by this input connector: - `From`: The sender of the email, including the display name if available. Examples: - `John Doe ` - `john.doe@example.com` - `Subject`: The subject of the email. ## Watched Mailbox (Gmail) The Conversion Service provides Gmail-specific connectors for seamless integration with Gmail accounts. These connectors support two authentication methods: - **App Passwords**: Authenticate using Gmail App Passwords, which requires 2-step verification. - **OAuth 2.0**: Authenticate using your organization’s OAuth credentials from Google Cloud Console. ### Watched Mailbox (Gmail App Passwords) The Watched Mailbox (Gmail App Passwords) connector converts all emails that are placed into a configurable mailbox on Gmail's IMAP server. After the conversion is finished, the mails are deleted. This connector uses Gmail App Passwords for authentication and has preconfigured Gmail IMAP settings. #### Settings - **Username**: Your Gmail email address. - **App Password**: The Gmail App Password generated for your account. - To use the Gmail App Password, you must first enable [2-Step Verification](https://support.google.com/accounts/answer/185839) on your Google account. - Once 2-Step Verification is enabled, generate an [App password](https://myaccount.google.com/apppasswords). - **Mailbox Path**: Path where all incoming messages are to be converted. - **Attachments only**: Turn on to process attached files only, and not the entire email body. - **Attach Skip Pattern**: Specify attachments of an email that are skipped by the Conversion Service. Use glob patterns such as `*` and `?`. When you enable this option, the connector ignores attachments that match the specified patterns. - **Expression**: Enter valid glob patterns separated by semicolons. Patterns can include wildcards such as `*` and `?` to match multiple or single characters. - **Examples**: - `*.exe` - Skip all attachments with the `.exe` extension. - `*.jpg` - Skip all `.jpg` image attachments. - `invoice?.pdf` - Skip attachments like `invoice1.pdf`, `invoiceA.pdf`, etc. - `*report.docx` - Skip attachments like `myreport.docx`, `yourreport.docx`, etc. - `*.exe;*.jpg;invoice?.pdf;*report.docx` - Skip attachments matching any of these patterns. #### Variables The following variables are set by this input connector: - `From`: The sender of the email, including the display name if available. Examples:`John Doe ` or `john.doe@example.com` - `Subject`: The subject of the email. ### Watched Mailbox (Gmail OAuth 2.0) The Watched Mailbox (Gmail OAuth 2.0) connector converts all emails that are placed into a configurable mailbox on Gmail's IMAP server using OAuth 2.0 authentication. This connector requires your organization to create and provide OAuth credentials from Google Cloud Console. #### Settings - **Username**: Your Gmail email address. - **OAuth 2.0 Client ID**: Your organization's OAuth 2.0 Client ID from Google Cloud Console. - **OAuth 2.0 Client Secret**: Your organization's OAuth 2.0 Client Secret from Google Cloud Console. - **Mailbox Path**: Path where all incoming messages are to be converted. - **Attachments only**: Turn on to process attached files only, and not the entire email body. - **Attach Skip Pattern**: Specify attachments of an email that are skipped by the Conversion Service. Use glob patterns such as `*` and `?`. When you enable this option, the connector ignores attachments that match the specified patterns. - **Expression**: Enter valid glob patterns separated by semicolons. Patterns can include wildcards such as `*` and `?` to match multiple or single characters. - **Examples**: - `*.exe` - Skip all attachments with the `.exe` extension. - `*.jpg` - Skip all `.jpg` image attachments. - `invoice?.pdf` - Skip attachments like `invoice1.pdf`, `invoiceA.pdf`, etc. - `*report.docx` - Skip attachments like `myreport.docx`, `yourreport.docx`, etc. - `*.exe;*.jpg;invoice?.pdf;*report.docx` - Skip attachments matching any of these patterns. #### OAuth 2.0 Setup Each organization must create their own Google Cloud Project and OAuth credentials. This ensures your email access is controlled by your organization. To obtain OAuth 2.0 credentials: 1. Contact your IT department to set up a Google Cloud Project. 2. Your IT department should: - Go to [Google Cloud Console](https://console.cloud.google.com/). - Create a new project for your organization. - Enable the Gmail API. - Configure the OAuth consent screen. - Create OAuth 2.0 credentials (desktop app type). 3. Once set up, your IT department will provide the Client ID and Client Secret. 4. Enter the credentials in the Conversion Service Configurator. #### Variables The following variables are set by this input connector: - `From`: The sender of the email, including the display name if available. Examples:`John Doe ` or `john.doe@example.com` - `Subject`: The subject of the email. ## Output Mailbox (IMAP) This connector copies files to a configurable mailbox on an IMAP server. In the case that the files are the original files coming from a Watched Mailbox input connector, the original email is copied as is. In all other cases, a new empty email is created with the files as attachment. ### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings - **Warnings**: The connector is active for all jobs that completed successfully with warnings - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings - **Error**: The connector is active for all jobs that failed - **Account Settings**: Configure the IMAP server account. - **Host/Port**: Host name and port of the IMAP server. - **SSL**: Type of encryption for connecting with the IMAP server. - **Username** and **Password**: Credentials for authenticating with the mail account. - **Mailbox Path**: Path where all incoming message are to be converted. - **File Set**: The files to be copied to the output mailbox. You can either copy the unprocessed input files (originals) or copy the resulting files from the workflow to the output folder. - **Preserve Input Mail Body**: Enable this option to copy the original mail body. Otherwise, a new empty email is created with the files as an attachment. ## Output Mailbox (Exchange Online) This connector copies files to a configurable mailbox on a Microsoft Exchange Online server. In the case that the files are the original files coming from a [Watched Mailbox Exchange Online](#watched-mailbox-exchange-online) input connector, the original email is copied as is. In all other cases, a new empty email is created with the files as attachment. ### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed. - **Username**: Credentials to authenticate with the server. - **Mailbox Path**: Path where all incoming message are to be converted. - **File Set**: The files to be copied to the output mailbox. You can either copy the unprocessed input files (originals) or copy the resulting files from the workflow to the output folder. - **Preserve Input Mail Body**: Enable this option to copy the original mail body. Otherwise, a new empty email is created with the files as an attachment. ## Output Mailbox (Gmail) The Conversion Service provides Gmail-specific output connectors that copy files to a configurable mailbox on Gmail's IMAP server. These connectors support two authentication methods: - **App Passwords**: Authenticate using Gmail App Passwords, which requires 2-step verification. - **OAuth 2.0**: Authenticate using your organization’s OAuth credentials from Google Cloud Console. ### Output Mailbox (Gmail App Passwords) This connector copies files to a configurable mailbox on Gmail's IMAP server using App Passwords authentication. In the case that the files are the original files coming from a Watched Mailbox input connector, the original email is copied as is. In all other cases, a new empty email is created with the files as attachment. This connector has preconfigured Gmail IMAP settings. #### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed. - **Account Settings**: Configure the Gmail IMAP server account. - **Username**: Your Gmail email address. - **App Password**: The Gmail App Password generated for your account. - To use the Gmail App Password, you must first enable [2-Step Verification](https://support.google.com/accounts/answer/185839) on your Google account. - Once 2-Step Verification is enabled, generate an [App password](https://myaccount.google.com/apppasswords). - **Mailbox Path**: Path where all messages are to be saved. - **File Set**: The files to be copied to the output mailbox. You can either copy the unprocessed input files (originals) or copy the resulting files from the workflow to the output folder. - **Preserve Input Mail Body**: Enable this option to copy the original mail body. Otherwise, a new empty email is created with the files as an attachment. ### Output Mailbox (Gmail OAuth 2.0) This connector copies files to a configurable mailbox on Gmail's IMAP server using OAuth 2.0 authentication. In the case that the files are the original files coming from a Watched Mailbox input connector, the original email is copied as is. In all other cases, a new empty email is created with the files as attachment. This connector requires your organization to create and provide OAuth credentials from Google Cloud Console. #### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed - **Account Settings**: Configure the Gmail OAuth 2.0 authentication. - **Username**: Your Gmail email address. - **OAuth 2.0 Client ID**: Your organization's OAuth 2.0 Client ID from Google Cloud Console. - **OAuth 2.0 Client Secret**: Your organization's OAuth 2.0 Client Secret from Google Cloud Console. - **Mailbox Path**: Path where all messages are to be saved. - **File Set**: The files to be copied to the output mailbox. You can either copy the unprocessed input files (originals) or copy the resulting files from the workflow to the output folder. - **Preserve Input Mail Body**: Enable this option to copy the original mail body. Otherwise, a new empty email is created with the files as an attachment. For information about OAuth 2.0 setup, see [OAuth 2.0 Setup](#oauth-20-setup) in the Watched Mailbox (Gmail OAuth 2.0) section. ## Send Email ### Send Email (SMTP) This connector sends an email to a configurable recipient. Email properties such as TO, CC, BCC, subject, and body text can be configured freely and may contain variable placeholders to include dynamic data. For example: - Information about the processing such as error message, warnings or events. - Variables set in the request of the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. - Query parameters from the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. The email can be configured to contain either the results or the original files as attachments. #### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings - **Warnings**: The connector is active for all jobs that completed successfully with warnings - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings - **Error**: The connector is active for all jobs that failed - **Account Settings**: Configure the SMTP server account. - **Host/Port**: Host name and port of the SMTP server. - **SSL**: Type of encryption for connecting with the IMAP server. - **Username** and **Password**: Credentials for authenticating with the mail account. Click **Validate** to test that the Conversion Service can connect to the mail server. - **Message**: Configure the message to be sent. - **To / CC / BB**: You can customize the recipients. Only one primary recipient can be configured per field. The email address may contain a display name in the form `Display Name
`. The address may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Subject**: The subject may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Body**: The body may contain [placeholder values](#placeholders-in-send-email-connectors). The body is sent as plain text, HTML content is not supported. - **Attachments**: The files to be included in the email. You can choose unprocessed input files (originals), copy the resulting files from the workflow to the output folder, or not include any attachments. ### Send Email (Exchange Online) This connector sends an email to a configurable recipient by using a Microsoft Exchange Online account. Email properties such as TO, CC, BCC, subject, and body text can be configured freely and may contain variable placeholders to include dynamic data. For example: - Information about the processing such as error message, warnings or events. - Variables set in the request of the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. - Query parameters from the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector The email can be configured to contain either the results or the original files as attachments. #### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed. - **Username**: Credentials to authenticate with the server. Click **Validate** to test that the Conversion Service can connect to the mail server. - **Message**: Message to be included in the send mail. - **To / CC / BB**: You can customize the recipients. Only one primary recipient can be configured per field. The email address may contain a display name in the form `Display Name
`. The address may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Subject**: The subject may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Body**: The body may contain [placeholder values](#placeholders-in-send-email-connectors). The body is sent as plain text, HTML content is not supported. - **Attachments**: The files to be included in the email. You can choose unprocessed input files (originals), copy the resulting files from the workflow to the output folder, or not include any attachments. ### Send Email (Gmail) The Conversion Service provides Gmail-specific email sending connectors that send emails using the Gmail SMTP server. These connectors support two authentication methods: - **App Passwords**: Authenticate using Gmail App Passwords, which requires 2-step verification. - **OAuth 2.0**: Authenticate using your organization’s OAuth credentials from Google Cloud Console. #### Send Email (Gmail App Passwords) This connector sends an email to a configurable recipient using Gmail's SMTP server with App Passwords authentication. Configure email properties such as TO, CC, BCC, subject, and body text. You can also add variable placeholders to include dynamic data in all the mentioned email properties. This connector has preconfigured Gmail SMTP settings. For example: - Information about the processing such as error message, warnings or events. - Variables set in the request of the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. - Query parameters from the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. The email can be configured to contain either the results or the original files as attachments. ##### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed. - **Account Settings**: Configure the Gmail SMTP server account. - **Username**: Your Gmail email address. - **App Password**: The Gmail App Password generated for your account. - To use Gmail App Passwords, you must first enable [2-Step Verification](https://support.google.com/accounts/answer/185839) on your Google account. - Once 2-Step Verification is enabled, generate an [App password](https://myaccount.google.com/apppasswords). - Click **Validate** to test that the Conversion Service can connect to the Gmail server. - **Message**: Configure the message to be sent. - **From**: The email address used to send the email. The address must correspond to the configured username; otherwise, you will not be able to send the email successfully. The email address may contain a display name in the form `Display Name
`. The use of placeholders is not permitted. - Examples: `john.doe@gmail.com` or `John Doe ` - **To / CC / BCC**: You can customize the recipients. Only one primary recipient can be configured per field. The email address may contain a display name in the form `Display Name
`. The address may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Subject**: The subject may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Body**: The body may contain [placeholder values](#placeholders-in-send-email-connectors). The body is sent as plain text, HTML content is not supported. - **Attachments**: The files to be included in the email. You can choose unprocessed input files (originals), copy the resulting files from the workflow to the output folder, or not include any attachments. #### Send Email (Gmail OAuth 2.0) This connector sends an email to a configurable recipient using Gmail SMTP server with OAuth 2.0 authentication. Configure email properties such as TO, CC, BCC, subject, and body text. You can also add variable placeholders to include dynamic data in all the mentioned email properties. This connector requires your organization to create and provide OAuth credentials from the Google Cloud Console. For example: - Information about the processing, such as error messages, warnings, or events. - Variables set in the request of the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. - Query parameters from the [REST Input](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) connector. Under the **File Set** configuration option you can set the email to contain either: - Results: The resulting files from the processing. - Originals: The original unprocessed input files. ##### Settings - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings. - **Warnings**: The connector is active for all jobs that completed successfully with warnings. - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings. - **Error**: The connector is active for all jobs that failed. - **Account Settings**: Configure the Gmail OAuth 2.0 authentication. - **Username**: Your Gmail email address. - **OAuth 2.0 Client ID**: Your organization's OAuth 2.0 Client ID from Google Cloud Console. - **OAuth 2.0 Client Secret**: Your organization's OAuth 2.0 Client Secret from Google Cloud Console. - Click **Validate** to test that the Conversion Service can connect to the Gmail server. - **Message**: Configure the message to be sent. - **From**: The email address used to send the email. The address must correspond to the configured username; otherwise, you will not be able to send the email successfully. The email address may contain a display name in the form `Display Name
`. The use of placeholders is not permitted. - Examples: `john.doe@gmail.com` or `John Doe ` - **To / CC / BCC**: You can customize the recipients. Only one primary recipient can be configured per field. The email address may contain a display name in the form `Display Name
`. The address may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Subject**: The subject may contain [placeholder variables](#placeholders-in-send-email-connectors) coming from the input connector. - **Body**: The body may contain [placeholder values](#placeholders-in-send-email-connectors). The body is sent as plain text, HTML content is not supported. - **Attachments**: The files to be included in the email. You can choose unprocessed input files (originals), copy the resulting files from the workflow to the output folder, or not include any attachments. For information about OAuth 2.0 setup, see [OAuth 2.0 Setup](#oauth-20-setup) in the Watched Mailbox (Gmail OAuth 2.0) section. ## Placeholders in Send Email connectors You can use placeholders in the recipient, subject, and body fields of the [Send Email (SMTP)](#send-email-smtp), [Send Email (Exchange Online)](#send-email-exchange-online), and [Send Email (Gmail)](#send-email-gmail) connectors. ### Recipient variables If a watched mailbox is used as input connector, the placeholder `[input:From]` can be used to refer to the sender of the original email. ### Subject variables If a watched mailbox is used as input connector, the placeholder [input:Subject] can be used to refer to the subject of the original email. For example, `Re: [input:Subject]` ### Body variables - `[output:ERROR]`: The error message. This placeholder is only available in case of an error. - `[output:WARNINGS]`: A list of warnings that happened during processing. One warning per line. - `[output:EVENTS]`: A list of everything that happened during processing. One event per line including the severity. - `[input:‹variable name›]`: A custom variable set by the input connector. --- ## Folder connectors Folder connectors either process all input files dropped in the folder (watched folder), add additional information to an output folder, or copy the output files to the folder after processing (output folder). ## Watched folder The watched folder connector converts all files that are placed into a configurable input directory. After the conversion is finished, the files are deleted. Additional configuration options are also available: files in subdirectories are also converted. The watched folder is available both on Windows and in Docker. To set up a watched folder: - On Windows Server, review [Integrate a watched folder](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server#configure-a-watched-folder) section in the getting started guide. - In Docker Compose, review [Configure containers using docker compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container#configure-containers-using-docker-compose) section for an example of a Docker Compose YAML file with watched folder configuration. **caution: This connector does not work well with Windows NFS share. If the watched folder is shared to be accessible by other computers using the NFS protocol, the service starts to process files before they are copied completely. This is due to a limitation in the Windows Server NFS implementation.** Possible solutions: - Use the SMB protocol instead of NFS - Use a two-stage process to place the file in the watched folder: 1. Copy the file to a temporary directory on the NFS share. 2. From there, move the file to the watched folder. ### Configuration options The following list includes available configuration settings for the Watched Folder connector: - **Folder Path**: The path of the input directory. - **Recursive**: Convert files in all subdirectories. If this option is enabled, the connector recursively searches all subdirectories for input files. Subdirectories are not deleted after the conversion is finished. - **File Skip Pattern**: Specify glob patterns for files to be skipped during the conversion process. The `*` and `?` glob patterns are supported. When you enable this option, the connector ignores files that match the specified patterns. - **Expression**: Enter valid GLOB patterns separated by semicolons. Patterns can include wildcards such as `*` and `?` to match multiple or single characters. - **Examples**: - `*.tmp` - Skip all files with the `.tmp` extension. - `*.jpg` - Skip all files with the `.jpg` extension. - `input?.pdf` - Skip files such as the `input1.pdf`, `inputA.pdf`, and similar. - `*input.pdf` - Skip files such as `myinput.pdf`, `yourinput.pdf`, and similar. - `*.tmp;*.jpg;input?.pdf;*input.pdf` - Skip files matching any of these patterns. - **Companion file**: Add metadata from a companion file. If this option is enabled, the connector expects a [companion file](#companion-file). ### Companion file The service expects a companion file for each input file, which has the same file name with a different (configurable) extension. The companion file must be XML, but can be structured arbitrarily. A list of variables can be defined with a corresponding XPath expression that is used to extract the value of the variable from the XML. **note: The XPath expressions always have to evaluate to a string.** Variables are used to pass through information to the output connector. They can be used in certain configuration values of some output connectors in the form of `[input:‹variable name›]`. For example, as argument in the [Execute Command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command) connector or as placeholders in the URL setting of the [REST Output](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-output-connectors) connector. **Example**: Companion file configuration | Key | Value | |--------------------|-----------------------------------------------------| | `myfirstvariable` | `string(/root/myelement/@myattribute)` | | `mysecondvariable` | `string(/root/myotherelement[@name="interesting"])` | Using the following companion file ```xml not interesting value my other value ``` results in the following variable substitutions usable in the output connectors: - `[input:myfirstvariable]` → my value - `[input:mysecondvariable]` → my other value ## Create text file This connector creates a text file with additional information in a configurable output directory. - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings - **Warnings**: The connector is active for all jobs that completed successfully with warnings - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings - **Error**: The connector is active for all jobs that failed - **Folder Path**: The path of the output directory. - **Filename**: The name of the text file. The filename may contain placeholder values such as: - `[input:NAME]`: The name of the input job. - `[input:‹variable name›]`: A variable set by the input connector. - **Content**: The content of the text file. The content of the file is customizable and may contain placeholders: - `[output:ERROR]`: The error message. This placeholder is only available in case of an error. - `[output:WARNINGS]`: A list of warnings that happened during processing. One warning per line. - `[output:EVENTS]`: A list of everything that happened during processing. One event per line including the severity. - `[input:NAME]`: The name of the input job. - `[input:‹variable name›]`: If the configured input connector supports variables, those can also be used as placeholders. - **Recreate Structure**: Recreate structure of the input folder. If the input connector is a watched folder, the output connector recreates the input folder structure in the output folder for each processed input file. The folder structure is merged with the pre-existing folder structure in the output folder. - **Overwrite**: If an output file has the same name as a file that already exists in the output folder, the preexisting file is overwritten. If this option is disabled, the new file is renamed using a suffix: " (1)", " (2)", and so on. There is no optional prefix added to the file results. ## Output folder The Output Folder connector copies files into a configurable output directory. The connector can either store the unchanged input files (originals), or the converted result files (results). - **Job Status**: Each output connector can only be active for a subset of result statuses: - **Success**: The connector is active for all jobs that completed successfully without warnings - **Warnings**: The connector is active for all jobs that completed successfully with warnings - **Success or Warnings**: The connector is active for all jobs that completed successfully with or without warnings - **Error**: The connector is active for all jobs that failed - **Folder Path**: The path of the output directory. - **File Set**: The files to be copied to the output folder. You can either copy the unprocessed input files (originals) or copy the resulting files from the workflow to the output folder. - **Recreate Structure**: You can choose to recreate structure of the input folder. If the input connector is a watched folder, the output connector recreates the input folder structure in the output folder for each processed input file. The folder structure is merged with the pre-existing folder structure in the output folder. - **Overwrite**: If an output file has the same name as a file that already exists in the output folder, the preexisting file is overwritten. If this option is disabled, the new file is renamed using a suffix: " (1)", " (2)", and so on. There is no optional prefix added to the file results. --- ## Action connectors This connector performs a specific action on the input and output files or on the output files only. ## Execute Command The Execute Command output connector executes a configurable command with arguments on files. In the arguments string either placeholder `[output:FILES]` can be used to pass a list of all files quoted and separated by a white space or `[output:FILE_‹i›]` to pass the i-th file. If the configured input connector supports variables, those can also be used as `[input:‹variable name›]`. The connector can either operate on the unchanged input files or the converted result files. --- ## REST connectors Learn how to use the REST connectors in the Conversion Service to automatically convert all files sent to a URL and send the results to a configurable URL. --- ## REST input (Simple API) The REST input connectors convert files sent in API requests. These connectors are also called the Conversion Service **Simple API**. Compared to the **Advanced API**, the Simple API returns converted files in just one API call. This documentation specific aspects of the Simple API in depth. If you need a tutorial or references, refer to: - [Simple API getting started guide](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/simple-api) - [Simple API references](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api) - [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json) ## Predefined connectors The Conversion Service provides a set of predefined connectors that leverage the Simple API: - REST API Archive PDF/A-2 - REST API Archive PDF/A-3 - REST API All to PDF Profile - REST API Merge Profile - REST API Ready to Print PDF/A-2 - REST API Ready for Web PDF/A-2 - REST API Ready for Email PDF/A-2 - REST API Repair Profile When the Conversion Service is running locally or on an IP address that you specify in the `baseURL`, you can test these connectors using the [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json) or the [Simple API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api). Note that in the Conversion Service Configurator, all of these connectors include **REST API** in their name. However, this **REST API** wording is not included in the API references or in the Postman collection. For example: **Archive PDF/A-2** in the Postman collection or API references is **REST API Archive PDF/A-2** in the Conversion Service Configurator. ## Custom REST connectors Choose your own workflow and profile in the Conversion Service Configurator Integrations tab. You can create your custom REST connectors that leverage Simple API with specific requirements that you set up. **info: To get started with your custom connector, review in the Simple API getting started guide.** [Create custom connection](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/simple-api#create-custom-connection). All of these connectors can use one of the following methods (the methods are also called connectors): - [REST input plain HTTP](#rest-input-plain-http) - [REST input JSON](#rest-input-json) ### REST input plain HTTP The REST Input connector sends files as single or multiple files in the request body. The connector then returns the response of whether the files were accepted or retrieves the result files. #### Request The connector can handle the following two request formats: - **Multiple files**: Send as `multipart/form-data` body. All files are merged into the same job. - **Single file**: Send as a raw request body. Set the `filename` URL query parameter in the URL to specify the name of the file. Otherwise, a default name is used. #### Options and variables Customize options and variables to either change the processing of the files in the workflow itself or in the output connector. - **Options**: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see [Job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) documentation. - **Variables**: Use variables to pass through information to the output connector. The format of the variables is: `[input:VARIABLE_NAME]`. Use these variables, for example, in the output connectors such as: - An argument in the [Execute Command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command) connector. - Placeholders in the URL setting of the [REST Output](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-output-connectors) connector. Both **Options** and **Variables** support placeholder syntax. Conversion Service supports query parameters and form data extraction. Query parameters are supported with the placeholder syntax for both request formats. Note that the form request format is not available for the **single file**: - `[query:QUERY-PARAM-NAME, 'DEFAULT-VALUE']` - `[form:FORM-DATA-NAME, 'DEFAULT-VALUE']` #### Response The connector can be configured to provide one of the following three different response types: - The call returns with an **HTTP status `202 Accepted`** immediately. The result is handled exclusively by the configured output connectors. - The call blocks until the job has finished and the first result file is returned as **response body**. - The call blocks until the job has finished and all result files are returned as **`multipart/form-data` response**. ### REST input JSON The REST Input connector uses JSON as a structured format for request and response. #### Request This connector allows to specify a job in a structured format (JSON). The files to be converted can either be referenced by URL or included directly in the job description. ```json { "name": "JOB_NAME", "options": [ { "name": "OPTION_NAME", "value": "OPTION_VALUE" } ], "variables": { "VARIABLE_NAME": "VARIABLE_VALUE" }, "data": [ // First file referenced by URL { "url": "http://example.com/path/to/file.jpg" }, // Second file inline { "fileName": "file.jpg", "content": "BASE64_ENCODED_FILE" }, // Third file with options { "fileName": "file2.jpg", "content": "BASE64_ENCODED_FILE", "options": [ { "name": "DOC.PASSWORD", "value": "USE_YOUR_PASSWORD" } ] } ] } ``` #### Options and variables Customize options and variables to either change the processing of the files in the workflow itself or in the output connector. - **Options**: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see [Job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) documentation. - **Variables**: Use variables to pass through information to the output connector. The format of the variables is: `[input:‹variable name›]`. Use these variables, for example, in the output connectors such as: - An argument in the [Execute Command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command) connector. - Placeholders in the URL setting of the [REST Output](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-output-connectors) connector. #### Response The connector can be configured to provide one of the following two different response types: - The call returns with an **HTTP status `202 Accepted`** immediately. The result is handled exclusively by the configured output connectors. - The call blocks until the job has finished and all result files are returned as a **structured JSON response**. ```json { "data": [ { "fileName": "file.pdf", "content": "BASE64_ENCODED_FILE" }, { "fileName": "report.txt", "content": "BASE64_ENCODED_FILE" } ] } ``` ### Relevant links to similar topics You can find more details about the Simple API in: - The [Simple API references](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api). - The [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json). - The [Simple API getting started guide](https://www.pdf-tools.com/docs/conversion-service/getting-started/api/simple-api). --- ## REST output Configure the REST output connector that returns converted files to a URL, which you can configure with the connection ID. ## REST Output The REST Output connector posts files as a multipart/form-data request to a configurable output URL. The URL may contain placeholder variables coming from the input connector. For example: - `http://example.com/path/on/server/?id=[input:id]` - `[input:url]` - `http://example.com/[input:serverpath]` The following additional configuration options are available: - The connector can either post the unchanged input files or the converted result files. - The form-data field name of the files. - Additional form fields can be configured where the values may contain placeholder values coming from the input connector. - The value of the HTTP `Accept` header can be configured freely. ### Authentication The connector supports username/password based authentication schemes such as Basic, Digest, NTLM, and Kerberos. The server must challenge unauthenticated requests properly with a 401 response. The connector preauthenticates subsequent requests to the same URL, i.e. send the necessary HTTP header without waiting to be challenged by the server. --- ## PDF Client for Conversion Service Using the PDF Client for Conversion Service, users on Windows machines in your network send files for processing to the Conversion Service running on your server. The files are automatically processed and sent back to the client machines. You can also use this desktop client to test your workflows and various configurations. In the background, the client interacts with the Conversion Service through a REST API. ## Set up and configure the client For information on how to download, install, and set up the client, review [Optional: Install and activate additional clients](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server#optional-install-and-configure-additional-clients) in the getting started guide. **note: You can also block any workflows so they do not appear as a conversion option in the client. For more information, review [Add workflows to the blacklist](#add-workflows-to-the-blacklist).** ### Set the service endpoint URL Before using the PDF Client, set up the service endpoint. You can change the service endpoint URL in the settings window of the PDF Client for Conversion Service. The default value is `http://localhost:13033/conversion/v1.0/rest`. To change the endpoint URL, follow these steps: 1. In the PDF Client for Conversion Service, click the three vertical dots , and then **Settings**. 1. In the **Service Host Address** field, insert the IP address or name of the server machine where the Conversion Service is installed. Alternatively, you can set the service endpoint URL by editing a configuration file: 1. Edit the URL of the `serviceEndpoint` in the project's `appsettings.json` file located in the `bin` directory of the installation path (for example: `C:\Program Files\Pdftools\Conversion Service Client\bin\appsettings.json`). ```json { "service": { "serviceEndpoint": "http://localhost:13033/conversion/v1.0/rest" } } ``` ### Add workflows to the blacklist You can blacklist individual workflows in the project's `appsettings.json` file in the directory `bin` of the installation directory (for example: `C:\Program Files\Pdftools\Conversion Service Client\bin\appsettings.json`). As a result, the blacklisted workflows will become invisible in the UI. To blacklist a specific workflow, add it to the `blacklistWorkflows` in the JSON file. ```json { "client": { "blacklistWorkflows": [ "Dossier", "Invoice" ] } } ``` ## Process documents To process documents, drag the documents to be processed to the input area. To remove individual documents from the list, select them and press the delete or back key. To remove all documents from the list, click **Clear List**. ## Configure conversion options In the client's interface, you can select the workflow and the profile you want to use for the conversion. Click the refresh icon to reload the workflows and profiles. The **Merge** toggle controls the processing mode. If you enable it, all input documents are gathered into one job, resulting in a single merged output document. If you turn off the **Merge** toggle, every document is processed in a separate job, resulting in one output document per input document. Choose where to store the resulting document(s). If you have enabled the **Merge** option, choose the file name of the output document. --- ## Integrate through Advanced API The Conversion Service provides two APIs: - **Simple API**: Process files in one API call. Get started fast with the Simple API, designed to solve common use cases of the conversion process. - **Advanced API**: Leverage fine-grained control over the conversion process, letting you convert many documents in bulk and check their status during the conversion process. Reliably process the harmonization of documents from various sources and prepare them optimally for your intended purpose. The Advanced API lets you schedule jobs and get service status information. The REST API is also used by the other clients, such as the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) and the [watched folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder). On this page, you can learn details about the Advanced API. ## Base URL You define the service base URL of the REST API in the Service configuration, with the `service-host-address` property. The default value is `http://localhost:13033/conversion/v1.0/rest`. ## API security By default, the API is available on the local machine only. If you want to access it remotely, you need to configure the computer's firewall accordingly. For example, you can use the Configurator GUI to set up a firewall port. When opening the port in the firewall, you should add a rule that is as strict as possible, to prevent connections from untrusted computers. **caution: The REST API is **designed for use in a protected intranet only**. It offers no user authentication or other security measures, such as mechanisms against denial-of-service attacks. If this is required, you should implement a web application firewall (WAF).** The Conversion Service supports cross-origin requests (CORS). Cross-origin request are required when sending requests using JavaScript from a browser. By default, requests from all origins are allowed. If necessary, you can restrict cross-origin requests to certain origins using the [service's configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container#cross-origin-requests-cors). ## Perform API calls The API supports XML and JSON format in the request and response body. In the event of an error, the API returns a HTTP status code and a **problem details object** ([RFC 7807](https://tools.ietf.org/html/rfc7807)). This object contains more information on the type and cause of the error. The object's `detail` property contains an explanation that helps you to troubleshoot the issue. Therefore, you should parse and use the problem details object (`application/problem+xml` or `application/problem+json`) whenever the returned HTTP status code indicates an error. **tip: Set the `Content-Type` and `Accept` parameters in the header to your preferred type.** You can find detailed information about the endpoints provided by the API in the [API reference](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/advanced-api). The API reference is also available as an OpenAPI YAML file inside the installation directory. You can view the YAML file in an OpenAPI editor or use it to generate client stub code for any programming language. :::tip[Try out the API in Postman] Pdftools lets you generate API requests for all our endpoints via our Postman collection. Postman is a free-to-use visual editing tool for building and testing APIs. [Postman](https://www.getpostman.com/) lets you easily edit API requests, view header information, and much more. 1. Save the [Conversion Service Advanced API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_advanced_api.postman_collection.json) as a JSON file. 2. Open the Postman API Client, select the Collections view, and click Import. 3. Drag the downloaded collection JSON file to the Import window. 4. Click **Conversion Service** in the Collections view. **Using the Conversion Service collection** When you use the Conversion Service Postman collection for the first time. here's the steps to proceed: 1. Specify the base URL: Ensure the baseURL in your collection variables specifies the host where your Conversion Service runs. 2. Get a list of the available workflows: Try out a simple request such as a list of the available workflows. This will help give you an overview of the available workflows in the Conversion Service, so you can then use one as an input parameter when you create a new job. 3. Process a file: Process your first file, bearing in mind the job processing sequence. ## Error codes If an error occurs during processing in a workflow, an error code with an explanatory message is returned. The following are common error codes: - **Internal**: The Conversion Service is not operational because of an internal issue, e.g. an incomplete installation. A detailed description of the problem is written to the service log file with *Error* severity level. The service administrator should be notified of the problem and submit a support request. No specific error message is returned because the issue is not related to the client or the request. This behavior can be changed in the service configuration. However, since the error is related to the service's configuration and the detailed description is designed to help the administrator resolve the problem quickly, the message might reveal internal configuration settings that you may not want to disclose to clients. Therefore, this is generally only recommended during installation and testing of the Conversion Service. - **External**: An error occurred while trying to use an external service or load a required external resource. - **Configuration**: The Conversion Service is not operational because of a configuration issue, e.g. an invalid or an incompatible setting. A detailed description of the problem is written to the service log file with *Error* severity level. The service administrator should resolve the problem with the help of the Configurator. - **Generic**: A generic error occurred. - **UnsupportedFormat**: The format of the input data is not supported. - **UnsupportedFeature**: An unsupported feature was requested. This may be a feature of the input data or one requested using options. - **Option**: An error occurred that is related to job or document options passed by the client. For example: - A required option is missing. - An option has an invalid or unsupported value. - **Canceled**: The job has been canceled by the user. - **Timeout**: The job has been canceled because of a processing timeout. - **Password**: The data cannot be processed because of a missing or invalid password. Retry the conversion and specify the missing password using the document option `DOC.PASSWORD`. This option can be added multiple times to try several passwords for a document or to specify passwords for multiple files, e.g. attachments or embedded files. - **Conformance**: There is a problem with the conformance of the input data. For example: - The input data's conformance is not supported. - The input data cannot be converted to meet the conformance required by the workflow and profile. - **Corrupt**: Data cannot be processed because it is corrupt. ## Process conversion jobs For a general overview of how jobs are processed by the Conversion Service, see [how the Conversion Service works](https://www.pdf-tools.com/docs/conversion-service/configure/how-cs-works) or the specific [workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/) such as [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) or [Convert to PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion) workflows. To schedule a job and retrieve its result, the sequence is as follows: There is no limit of the number of jobs that can be started concurrently. The service processes the jobs in the order they were created, using the highest concurrency allowed by the system's CPU and the license. Nonetheless, it is recommended to not start much more jobs than the service can process. For example, on a machine with 8 CPU cores and a license for 8 cores, not much more than 8 jobs should be started. To determine the maximum concurrency, the whole system and configuration must be taken into consideration. Dependent systems such as an OCR service or Office conversion may further limit the maximum concurrency. ## Get service information These methods return information regarding the service's overall status: - `getServiceStatus` - `listJobs` - `listWorkflows` ### Get service status The `getServiceStatus` method can be used to retrieve general status information. You can use this method to verify if the service is running, to monitor service health. In addition, you can get information on the service's load and general job count. For more information, see [Get the Service Status endpoint](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-service-status). ### Get a list of jobs The `listJobs` method returns a list of all jobs and their status. You can use this method to see what tasks are currently executing. For more information, see [List all jobs endpoint](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/list-jobs). ### Get a list of all workflows The `listWorkflows` method returns a list of all workflows and their profiles. For more information, see [List all workflows endpoint](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/list-workflows). --- ## Integrate via shell client (CLI) The command line application client (`pdfclient`) lets you automate conversion tasks in a shell script or as a scheduled task. The shell client application interacts with the Conversion Service through the [REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api). The application creates jobs based on its input parameters. The jobs are then uploaded in parallel to the Conversion Service and the shell client monitors the completion before the output files are downloaded. In verbose mode (option `-v`), a detailed report including all performed actions on the documents is written to the console. If warnings or errors occur during processing, they are reported. ## Using the CLI The installer adds `pdfclient` to the `PATH` environment variable during installation. When you run `pdfclient` without any arguments, it displays a usage message to standard output. ```title="CLI" pdfclient [options] [...] ``` | Option | Description | | ------------------- | ------------------------------------------------------------------------------ | | **Generic options** | | | `-url url` | Service endpoint URL (default: http://localhost:13033/conversion/v1.0/rest) | | `-v` | Verbose mode | | **Job options** | | | `-w wf` | Workflow to use for processing; otherwise the default workflow is used | | `-p prof` | Profile to use for processing; otherwise the default profile is used | | `-s` | Process all input files as separate jobs, output must be an existing directory | | **Input options** | | | `-pw pwd` | Password, applies to subsequent input | | `-r` | Recursive, include files in subdirectories | | **Output options** | | | `-i` | Prompt before overwriting files | | `-u` | Create unique file name instead of overwriting files | | **Input ** | | | `file` | Single file, e.g. `input.pdf` | | `wildcard` | All matching files, e.g. `C:\path\to\files*.pdf` | | `directory` | All files in a directory, e.g. `C:\path` | | **Output** | | | `file` | Single output file. If no extension is specified, it is added automatically. | | `directory` | Existing output directory, required with option `-s` | | **Return codes** | | | `0` | Success | | `1` | Warnings occurred | | `2` | Error | ## Basic example In this example, the CLI sends the `file.pdf` and `encrypted.pdf` to the Conversion Service through the REST API endpoint URL `http://:/conversion/v1.0/rest` and saves the result as `output.pdf`. The option `-v` turns on verbose mode, option `-url` sets the service base URL, and option `-pw` supplies the password for `encrypted.pdf`. If the service base URL (`-url`) is not set, `localhost` and the default port are used. ```title="CLI" pdfclient -v -url http://:/conversion/v1.0/rest file.pdf ^ -pw encrypted.pdf output.pdf ``` **note: Unless you have extended the PATH environment setting to include the installation directory of the Conversion Service, you have to specify the full file path to call the `pdfclient.exe` program.** ## Workflow and profile Use the `-w` and `-p` options to select a specific workflow and profile for the job. In this example, the workflow is set to **Archive PDF/A-2** and the profile is set to "myCustomProfile". If the options are not specified, the service’s configured default workflow and profile are used. ```title="CLI" pdfclient -w "Archive PDF/A-2" -p "myCustomProfile" input.pdf output.pdf ``` ## Wildcards Sends all files with extension `.ext` from the current working directory and all subdirectories to the Conversion Service, and saves the result as a single output document `C:\path\to\output.pdf`. Process the files with extension `.ext` as separate jobs and save the results in `C:\path\to\output`. The output directory must already exist. Existing output files are overwritten by default. Output options such as creating unique filenames instead of overwriting existing files are explained in the usage of the tool. ``` pdfclient -r *.ext C:\path\to\output.pdf ``` ## Batch processing Sends the files inside `C:\path\to\input`, including all subdirectories, to the Conversion Service. It saves the results in `C:\path\to\output` with the same file structure as in the input directory. Existing output files are overwritten. Output options such as creating unique filenames instead of overwriting existing files are explained in the usage of the tool. ``` pdfclient -r -s C:\path\to\input C:\path\to\output ``` --- ## Migrating from 3-Heights® Document Converter This guide explains how to migrate your existing 3-Heights® Document Converter installation to the Conversion Service. ## Before you begin Before you start to migrate to the Conversion Service, check that your system meets the [system requirements](https://www.pdf-tools.com/docs/conversion-service/migrate/installation#system-requirements) for the Conversion Service. **caution: Since the Conversion Service is a completely redesigned product, there _may not be a Conversion Service-equivalent feature_ for some 3-Heights® Document Converter features.** It is recommended that you **[check feature compatibility](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#feature-compatibility-between-products)** first. To learn more about how the Conversion Service compares to the 3-Heights® Document Converter, see the [high-level architecture](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#high-level-architecture) and [integration options](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#integrations). ## Formats supported by the Conversion Service The [input](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#supported-input-formats) and [output formats](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#supported-output-formats) depend on the specific workflow used in the Conversion Service. For more information on workflows and how they compare to the 3-Heights® Document Converter functionality, see **[Job and document processing](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#job-and-document-processing)** in the Conversion Service. Depending on the specific workflow, [nested files and attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#supported-nested-files-and-attachments) can be processed by the Conversion Service. ## Installing the Conversion Service The Conversion Service has an [MSI installation package](https://www.pdf-tools.com/docs/conversion-service/update/) to install the service on your infrastructure. There are differences in the [default folder locations](https://www.pdf-tools.com/docs/conversion-service/migrate/installation#default-folder-locations), and how [log files](https://www.pdf-tools.com/docs/conversion-service/migrate/installation#log-files) and [configuration files](https://www.pdf-tools.com/docs/conversion-service/migrate/installation#configuration-files) are named and handled between the Conversion Service and 3-Heights® Document Converter. ## Configuring the Conversion Service The Conversion Service uses a [Configurator](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) to set up profiles, i.e. settings, for the pre-defined workflows. To help you translate 3-Heights® Document Converter options to the Conversion Service settings, see [Job and document processing options](https://www.pdf-tools.com/docs/conversion-service/migrate/job-processing). ## Integrating with the Conversion Service The Conversion Service can be integrated into your system using multiple interfaces depending on your specific requirements. Many of the [integrations](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/) offered with the 3-Heights® Document Converter are available also for the Conversion Service. See [Integrations](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/). :::tip[Need further assistance?] If you require additional information on how to **migrate your specific installation and setup to the Conversion Service**, please contact [Pdftools Support](mailto:pdfsupport@pdf-tools.com). --- ## Errors and warnings The handling of errors and warnings is much more flexible in the Conversion Service and easier to understand. The user or operator has the full control over each aspect of it. | | Conversion Service | 3-Heights® Document Converter | |---|---|---| | **Errors** | | | | Possible **error code values** | Fixed documented set of possible error codes | Positive integer value, can also be a system error code. Common values are documented | | Identify the **affected input document within a multi-document job** | If applicable, the ID of the corresponding document is provided at the interface. (`dataId`) For more information, see the `dataId` schema in the [Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result) endpoint | Manually (e.g. with log files) | | Identify the **affected part within a nested input document** (e.g. attachment) | If applicable, a string identifying the affected part is provided at the interface. (`dataPart`) For more information, see the `dataPart` schema in the [Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result) endpoint | Manually (e.g. with log files) | | Identify **errors in the static service configuration** | Error code `Configuration` | Manually (e.g. with log files) | | Identify **errors in the runtime options** (job options, document options) | Error code `Option` | Manually (e.g. with log files) | | Identify **internal service errors** | Error code `Internal`. More details are provided in the service log file. | Manually (e.g. with log files) | | **Warnings** | | | | Possible **warning code values** | Workflow-specific set of possible values | Negative integer error code value | | **Multiple warnings** | All warnings are reported in the list of conversion events. For more information, see the `events` schema in the [Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result) endpoint. | Only a single warning is reported. | | Identify the **affected input document within a multi-document job** | If applicable, the ID of the corresponding document is provided at the interface. (`dataId`) (For more information, see the `dataId` schema in the [Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result) endpoint) | Manually (e.g. with log files) | | Identify the affected part within a nested input document (e.g. attachment) | If applicable, a string identifying the affected part is provided at the interface. (`dataPart`) For more information, see the `dataPart` schema in the [Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result) endpoint | Manually (e.g. with log files) | | **Ignore certain warning types** | Can be configured for all possible warning types in the profile configuration. | Can only be configured for some types of warnings (e.g. options `WARNSIGNATURES PDFA.XMPWARNINGS`, `PDFA.WARNVISDIFF`, etc.) | | Treat certain **warning types as errors** | Can be configured for all possible warning types in the profile configuration. | Can only be configured with job options for some types of warnings (e.g. option `PDFA.CONVERSIONERRORMASK`). | **info: For more information on how to set up the service logs to track errors and warnings, see **[Service logs](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log)**.** **tip: For more information on the `events`, `dataId`, and `dataPart` schemas, see the **[Get job result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result)** endpoint.** --- ## Installation and configuration This page explains key information such as system requirements and configuration to take into consideration when migrating to the Conversion Service from the 3-Heights® Document Converter. **tip: Want to get started with installing the Conversion Service on a compatible operating system? ** See **[Install Conversion Service](https://www.pdf-tools.com/docs/conversion-service/update/)**. ## System requirements The system requirements for migrating to the Conversion Service from 3-Heights® Document Converter are as follows: | | Conversion Service | 3-Heights® Document Converter | | -------------------------------------- | :------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | | Microsoft Windows | Windows Server 2019, 2022, 2025 (all 64-Bit) | Windows Server 2008 R2, 2012, 2012 R2, 2016, 2019, 2022 (all 64-Bit) | | Microsoft Windows Terminal Server role | Not required | Recommended | | Microsoft Office versions | Office 2021 (64 Bit), 2024 (64 Bit) and Microsoft 365 (64 Bit) | Office 2010, 2013, 2016 and 2019 | | Microsoft Office language setting | English (US) | English (recommended), German | | Microsoft .NET Runtime | .NET Desktop Runtime 8.0 + ASP.NET Core Runtime 8.0 | .NET Framework 4.7 | | Microsoft Universal CRT | Not required | Required | | Microsoft Internet Explorer | Not required | Required for conversion of web archives and HTML bodies of emails (if configured) | | Adobe Acrobat Reader | Not required (XFA forms in PDF are not supported) | 10 or higher (required for conversion of XFA forms in PDF) | ## Default folder locations There are several differences in the default folder locations used in the Conversion Service. | | Conversion Service | 3-Heights® Document Converter | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Installation directory (`%INSTALLATION_DIRECTORY%`) | `C:\Program Files\Pdftools\Conversion Service` | `C:\Program Files\PDF Tools AG\3-Heights(TM) Document Converter Enterprise` | | Program data directory (`%PROGRAMDATA_DIRECTORY%`) | `C:\ProgramData\Pdftools\Conversion Service` | -- | | Log directory | `%PROGRAMDATA_DIRECTORY%\Logs` | `%INSTALLATION_DIRECTORY%\log` `%INSTALLATION_DIRECTORY%` (Watched Folders only) | | Temporary file directory | `%PROGRAMDATA_DIRECTORY%\TemporaryWorkFiles` `%PROGRAMDATA_DIRECTORY%\TemporaryWorkFolders` | `%INSTALLATION_DIRECTORY%\Temp` | | Configuration file directory | `%INSTALLATION_DIRECTORY%\bin` | `%INSTALLATION_DIRECTORY%` | | Documentation directory | Online documentation only | `%INSTALLATION_DIRECTORY%` | For more information, see **[Install the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/update/)**. ## Log files All verbose information is written to the [Service log files](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log) in the Conversion Service. The names of the log files are different when migrating to the Conversion Service from the 3-Heights® Document Converter. | | Conversion Service | 3-Heights® Document Converter | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------- | | Main service log file name | `ConversionService-Service.log` (current) `ConversionService-Service-.log` (past) | `o2psrv-.log` `o2psrv-w-.log` | | Worker log file name | `ConversionService-Service.log` (current) `ConversionService-Service-.log` (past) | `o2pwsc-1-.log` `o2pwsc-2-.log`... | | Watched Folder log file name | `ConversionService-Connections.log` (current) `ConversionService-Connections-.log` (past) | `O2PWFS-log-.log` | | Mail Folder log file name | `ConversionService-Connections.log` (current) `ConversionService-Connections-.log` (past) | `O2PMFS.log` (current) `O2PMFS-.log` (past) | | Configurator log file name | `ConversionService-Configurator.log` (current) `ConversionService-Configurator-.log` (past) | `O2PConfigure.log` | | Setup Wizard log file name | `ConversionService-Configurator.log` (current) `ConversionService-Configurator-.log` (past) | `DocConvInstallConfig-.log` | ## Configuration files You configure the Conversion Service using the Configurator. **warning: Unlike the 3-Heights® Document Converter, the configuration files must not be edited manually. The [configurator](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service) must be used to change any settings. Editing the Conversion Service configuration files **may cause the service to fail**. Do not make any changes to these files.** For more information on configuring the setup for your installation, see **[Configure the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service)**. | | Conversion Service | 3-Heights® Document Converter | |----------------------------------|--------------------|-------------------------------| | General service settings | `appsettings.json` | `O2PSRV.exe.config` | | Worker settings | | `O2PWSC.exe.config` | | Job/Document processing settings | `Workflows.xml` | `O2PWSC.ini` | | Watched Folder settings | `Connections.xml` | `O2PWFS.ini` | | Mail Folder settings | `Connections.xml` | `O2PMFS.ini` | ### Configuring Microsoft Office Similar to the 3-Heights® Document Converter, the Conversion Service uses Microsoft Office applications to process jobs containing Word, Excel, and PowerPoint documents. **caution: The Conversion Service **cannot be installed on the same machine** where the 3-Heights® Document Converter client or service is running due to conflicts between Microsoft Office configurations.** If you plan to run both services in parallel while migrating to the Conversion Service, then you need to install the Conversion Service on a separate machine. You can convert Microsoft Office files using: - a local Microsoft Office installation - the Microsoft Office for the web service To set up the Conversion Service, see **[Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion)**. --- ## Command Line client The command line application client (`pdfclient`) lets you automate conversion tasks in a shell script or as a scheduled task. For more information on using the Conversion Service CLI, see [Shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client). ## Quick reference of CLI options The table lists the key command line options for the 3-­Heights® Document Converter and gives you the equivalent option in the Conversion Service. | 3-­Heights® Document Converter | Conversion Service | Note | | ------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------ | | `-sp ` | `-url ` | Enter Service endpoint URL | | `-l` | Not available | List know file extension | | `-o ` | `pdfclient [...] ` (last argument) | Output path (file or directory) | | `-j ` | `-w -p ` | Job configuration | | `-b ` | `-pw ` | Document options (only password) | | `-px` | Not supported | Additional parameter file | | `-v` | `-v` | Verbose mode | | `-ax ` | Not supported | Metadata: can be added in the profile configuration. | | `-share` | Not supported | Pass files via shared file system. | | Not supported | `-s` | Process all input files as separate jobs, output must be an existing directory | | Not supported | `-r` | Recursive, include files in subdirectories | | Not supported | `-i` | Prompt before overwriting files | | Not supported | `-u` | Create unique file name instead of overwriting files | --- ## Integrate with the Conversion Service The Conversion Service offers many of the same integration possibilities as the 3-­Heights® Document Converter such as watched folders, mail folders, a GUI client application, and a command line client application. However, there are some key differences: - **Job-based main service interface**: The .NET-remoting interface has been replaced by a [REST web service](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api). - **Single-call SOAP web service interface**: This interface has been replaced by [REST input connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/) that can be combined freely with other connector-based integration options (unlike the SOAP interface). - **Windows File Explorer extension**: Previously in the 3-Heights® Document Converter, you could use an extension that would let you convert files directly from the Windows File Explorer. This feature is not available in the Conversion Service; however, you can use the [PDF client](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client) to convert your files from the desktop. | Integration type | Conversion Service | 3-Heights® Document Converter | | -------------------------------------------------------- | ------------------ | ----------------------------- | | [GUI client application](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client) | Yes | Yes | | [Command line client application](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/CLI) | Yes | Yes | | [Watched folders](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-folders) | Yes | Yes | | [Mail folders](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-mail-folders) | Yes | Yes | | [Send email](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-folders) | Yes | Yes | | [Web service interface (REST)](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api) | Yes | No | | Web service interface (SOAP) | No | Yes | | MS Office add-in | Yes | Yes | | Windows Explorer extension | No | Yes | | Client library | No | Yes | --- ## Office and Windows File Explorer integration Both the 3-­Heights® Document Converter and the Conversion Service support Office Add-ins. The Office Add-ins are a simple way to convert documents directly from an Office application in a client machine. They are available for Microsoft Word, Excel, PowerPoint, and Outlook. Office Add-ins are installed when you [install the Client application](https://www.pdf-tools.com/docs/conversion-service/update/) using the Client MSI installation package (`conversion-service-client-.msi`). The client application cannot be installed on the same system as the 3-­Heights® Document Converter Service or the Conversion Service is running on. :::note[Important] Office Add-ins don't convert the files locally, but use a remote Conversion Service for conversion. You must [configure Office conversion](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion) on the server installation first. ## Supported Office files The table shows the Microsoft Office input formats supported by the Conversion Service and those originally supported by the 3-Heights® Document Converter. | Format | Conversion Service | 3-Heights® Document Converter | | ---------------------------------------------------------- | ------------------ | ----------------------------- | | MS Word binary formats (DOC, DOT) | _Yes_ | _Yes_ | | MS Word OOXML-based formats (DOCX, DOCM, DOTX, DOTM) | _Yes_ | _Yes_ | | WordML / WordprocessingML (XML) | _Yes_ | _Yes_ | | MS Excel binary formats (XLS, XLT) | _Yes_ | _Yes_ | | MS Excel OOXML-based formats (XLSX, XLSM, XLTX, XLTM) | _Yes_ | _Yes_ | | SpreadsheetML (XML) | _Yes_ | _Yes_ | | MS PowerPoint binary formats (PPT, PPS) | _Yes_ | _Yes_ | | MS PowerPoint OOXML-based formats (PPTX, PPTM, PPSX, PPSM) | _Yes_ | _Yes_ | | MS Project | _No_ | _Yes_ | | MS Visio | _No_ | _Yes_ | ## Windows File Explorer integration The 3-­Heights® Document Converter offers Windows Explorer integration that lets you convert files directly from the File Explorer window. This feature is not supported by the Conversion Service. --- ## Watched Folders Watched Folders automatically convert documents copied to a preconfigured input folder to a preconfigured output folder. Optionally, files in subdirectories are also converted. The Watched Folders depend on a Windows service. In the Conversion Service, watched folders are configured as a [connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/). **tip: For more information about watched folders in the Conversion Service, see **[Folder Connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors)**.** ## Creating a new watched folder While you used the Configuration Editor to create new watched folders in the 3-­Heights® Document Converter Service, you use the Conversion Service Configurator to add watched folders. During installation, the Conversion Service creates an example watched folder configuration for PDF/A-2 conversion: - _C:\ConversionService\Archive PDFA-2_: Main folder for the sample configuration. - _Input_: Folder where the input files are dropped for conversion. - _Output_: Folder where the converted output files are stored if the conversion was successful without warnings. - _Warning_: Folder where the converted output files are stored if warnings are generated during conversion. This is also where the [log file](#log-files) containing the warnings for that file is stored. - _Failed_: Folder where the input file is moved if the conversion has failed. This is also where the [log file](#log-files) containing the error for that file is stored. You can change the location of this folder to suit your requirements and add any number of additional configurations. **Process for creating a new watched folder configuration in the Conversion Service** 1. Open the Conversion Service Configurator. 2. Go to the **Integration** tab. 3. Press **Add** to create a new configuration. | 3-­Heights® Document Converter | Conversion Service | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | | | 4. Configure the [desired watched folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors). | 3-­Heights® Document Converter | Conversion Service | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | | | | Root directory | Not applicable | | Pickup | Input | | Output | Output with _Success_, _SuccessOrWarnings_ | | Warnings | Output with _Warnings_ | | Failed | Output with _Failed_ | ## Job & document options Unlike 3-­Heights® Document Converter where you could set job and document options with `-j` `Set Converter Job Options` and `-b` `Set Document Options` commands, the options are not configured in the watched folder itself. A workflow and profile needs to be selected in the Configurator when creating or editing your Watched Folder configuration. The settings within the selected [Workflow-Profile combination](https://www.pdf-tools.com/docs/conversion-service/workflows/) are taken into account when converting documents placed in the watched folder. | 3-­Heights® Document Converter | Conversion Service | | ------------------------------------------------------------ | --------------------------------------------------------------- | | | | ## Log files In the 3-­Heights® Document Converter, an error log file was created in the output directory in the event of errors during the conversion process. To receive a detailed log file in the Conversion Service, you simply configure a new output connector [Create Text File](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#create-text-file). You configure what kind of logs you want to receive and where you want to store these files. | 3-­Heights® Document Converter | Conversion Service | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | | | ## Recursive conversion In the 3-­Heights® Document Converter by setting the option `-R`, the Watched Folder service searches in subfolders of drop directory also. The output is stored in corresponding subfolder of the output directory. In the Conversion Service, these two features can be controlled separately: - If the _Recursive_ option is enabled on a [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder), the service also searches for files in subfolders of the input folder. This works in combination with any type of output connector, not just output folders. - If the _Recreate Structure_ option is enabled on a corresponding [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder), the output files are stored in corresponding subfolders inside the output folder. If the setting is disabled, all files are stored directly in the output folder without subfolders, regardless of their original location within the input folder. | Recursive search | Recreate folders | | ----------------------------------------------------- | -------------------------------------------------------------- | | | | ## Prefixes and overwriting files In the 3-­Heights® Document Converter, you could use a job-specific prefix to number the files to prevent files with the same name from being overwritten. The Conversion Service does not support prefixes. Instead, the _Overwrite_ option in the [Output Folder connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) lets you determine whether you want to rename the output file if another file with the same name exists or overwrite the existing file. ## Migrating watched folder options This table contains the equivalent setup in the Conversion Service to migrate your existing 3-­Heights® Document Converter configuration. | Option in 3-­Heights® Document Converter | Equivalent in Conversion Service | Note | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AutoDelete` | [Output Folder connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder): _Job Status = Success_ and _Fileset = Originals_ | For `true`, **don't** configure an output folder for these conditions. | | `AutoDeleteAll` | [Output Folder connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder): _Job Status = Error_ and _Fileset = Originals_ | For `true`, **don't** configure an output folder for these conditions. | | `JobPrefix` | [Output Folder connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder): _Overwrite toggle off_ | If the "Overwrite" option is disabled, filename conflicts can be avoided by using a suffix: " (1)", " (2)", and so on. Adding a prefix to be used where there are no name conflicts is not supported. | | `KeepTimeForFailed` | Not available (`0`) | Files in the output folders are never deleted automatically | | `KeepTimeForSucceeded` | Not available (`0`) | Files in the output folders are never deleted automatically | | `LogLevel` | Custom log | Create [custom logs using NLog](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log#custom-logs) | | `LogPath` | Log directory | This setting applies to all services and client applications of the Conversion Service | | `PollingInterval` | Not applicable | | | `ServiceHost` | Service Host Address | [Conversion Service Configurator](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service#service-host-address): _Conversion Service tab > Configuration_ / The computer name or network address where the Conversion Service hosted. | | `ServicePort` | Service Host Address | Default Port: http://localhost:13033/conversion/v1.0/rest | | `Threads` | Not applicable | The total number of Watched Folders is visible in the [Integration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections) tab. | | `Thread` | Configured watched folder | All configured Watched Folders listed in the [Integration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections) tab. | | `WorkerThreads` | Not applicable | Concurrency depends on the system’s CPU and the license | ## Migrating watched folder thread options This table contains the equivalent setup in the Conversion Service to migrate your existing 3-­Heights® Document Converter configuration. | Option in 3-Heights® Document Converter | Equivalent in Conversion Service | Note | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-b ‹opt›` set document options | Not applicable | All settings have to be configured in the [profile settings](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). [Document options](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#job-and-document-processing) are not available for watched folders. | | `-di` delete input files (in job control files) | Not applicable | | | `-j` set converter job options | Use [Profile Settings](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) | Job options are configured in the dedicated profile. See [Job options](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#job-and-document-processing) | | `-l` create error log | [Create Text File](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#create-text-file) | Explicitly create an output connector to write the log as a text file inside the corresponding output folder. | | `-o` specify output directory | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Success or SuccessOrWarning_ | Add an output folder connector with the corresponding conditions. | | `-of` specify failed directory | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Error_ | Add an output folder connector with the corresponding conditions. | | `-op` unprefix output | Not applicable | | | `-os` specify directory for succeeded jobs | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Success; File Set -> Originals_ | Add an output folder connector with the corresponding conditions. | | `-ow` ignore warnings | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> SuccessOrWarning_ | Use the condition `SuccessOrWarnings` instead of just `Success` for your main output folder. You can configure the events to raise a warning or error in more detail in the [Profile configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles): _Conversion Settings -> Warnings_ | | `-owf` warnings output folder | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Warnings_ | Add an output folder connector with the corresponding conditions. | | `-ox` IDX name | Not applicable | Only used in conjunction with `-1` and `-1l`, which are both not supported. | | `-o0` keep output | Not supported | No output files are produced for failed conversions. | | `-o1` second output directory | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Success_ | Create additional output folder within your watched folder | | `-o2` force succeeded | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) connector: _Job Status -> Success_ / _SuccessOrWarning / Error; File Set -> Originals_ | The Conversion Service allows an arbitrary number of output directories. | | `-R` Search for dropped files | [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder): _Recursive_ and [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder): _Recreate Structure_ | Enable both settings. | | `-u` unzip output to folder | Not applicable | The Conversion Service does not produce ZIP output files. | | `-w` specify the path to the root directory | Not applicable | All folder paths can be configured individually. | | `-wd` specify the drop path | [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder) | Configure the input folder within the watched folder | | `-wfi` ignore files with certain extensions | [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder): File Skip Pattern | To set up the File Skip Pattern specify GLOB patterns separated by semicolons. | `-wfs` process only files with certain extensions | Not available | | | `-1` & `-1l` single page output (TIFF) | Not supported | TIFF output is not supported by the Conversion Service. | --- ## Watched Mail Folders Watched Mail Folders (also known as watched mailboxes) convert all emails that are placed into a configurable mailbox. In the 3-­Heights® Document Converter, a Mail Folder Windows service is used to convert email messages to PDF format. In the Conversion Service, watched mailboxes are configured as [connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/). The Conversion Service provides several connectors that are equivalent to the 3-­Heights® Document Converter Mail Folder service features: #### Folder types for input folders (Pickup Folder) | 3-­Heights® Document Converter | Conversion Service | Note | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | IMAP Folder | [Watched Mailbox (IMAP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-imap) | A connector that converts all mail that are placed into a configurable mailbox on an IMAP server | | Exchange Online Folder | [Watched Mailbox (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-exchange-online) | A connector that converts all mail that are placed into a configurable mailbox on an Exchange Online server | | File System Directory | [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder) | A connector that watches a directory and converts all incoming files | #### Folder types for output folders (Output Folder, Failed Folder, Succeeded Folder) | 3-­Heights® Document Converter | Conversion Service | Note | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Folder relative to Pickup Folder | Corresponding output connector type | Explicitly select a output connector that corresponds to the type of the Pickup folder: [Output Mailbox (IMAP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-imap) or [Output Mailbox (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-exchange-online) or [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) | | Mail recipient (SMTP) | [Send Email (SMTP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-smtp) or [Send Email (Exchange Online)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-exchange-online) | For Exchange Online accounts, both connector types can be used. The Send Email (Exchange Online) connector uses the HTTP protocol (Microsoft Graph API) instead of SMTP. | | File System Directory | [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) | | | File System Directory with _Completion Action_ | [Execute Command](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/other-connectors#execute-command) | Important: In contrast to the "Completion Action", the "Execute Command" connector operates on **temporary** files located in an internal directory. The command itself is responsible for copying the files to their final destination and **must not** delete the files provided as arguments. | ## Setting up an IMAP folder You can set up an IMAP folder configuration similar to that used in the 3-­Heights® Document Converter, In this example, the emails are retrieved from the Inbox folder (`mail.yourcompany.com/user:encryptedpassword/INBOX`), converted to PDF/A format. The converted files are then sent to an email address using the SMTP server (`smtp:user@somewhere.org`). Emails that couldn't be converted are placed in the Failed folder, and those converted are placed in the Succeeded folder. To set up this configuration in the Conversion Service: 1. Open the Conversion Service Configurator 2. Go to the **Integration** tab. 3. Press **Add**. 4. Add an **Input** connector: - Select [Watched Mailbox (IMAP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-imap) - Configure the account settings. - Click on the icon in the "Mailbox Path" field and select a mailbox. 5. To send the results as an email, add an **Output** connector: - Select [Send Email (SMTP)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-smtp). - Configure the account settings and message properties. 6. To configure a "Succeeded" folder, add an **Output** connector: - Select [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder) - In File set, select _Originals_. 7. To configure a "Failed" folder, add an **Output** connector: - Select [Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder). - In Job status, select _Error_. In File set, select _Originals_. ## Migrating mail folder service settings This table contains the equivalent setup in the Conversion Service to migrate your existing 3-­Heights® Document Converter configuration. | 3-­Heights® Document Converter | Conversion Service | Note | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FileNameTemplate` | Not configurable (`%SUBJ`) | For emails, the subject is always used as filename. | | `UseSubject` | Not configurable (`true`) | For emails, the subject is always used as filename. | | `MaxAttachmentName` | Not configurable | The output filename from the workflow is used as-is without modification. | | `JobPrefix` | [Output Folder connector](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder): Disable **Overwrite** | If the "Overwrite" option is disabled, filename conflicts are avoided by using a suffix: " (1)", " (2)", and so on. Adding a prefix to be used where there are no name conflicts is not supported. | | Folder X (`Threads`, `ThreadX` in `o2pmfs.ini`) | Configured mail folder | All configured Mail Folders listed in the [Integration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-connections) tab. See [Migrating watched mail folder options](#migrating-watched-mail-folder-options). | | `LogPath` | Log directory | In the Conversion Service, this setting applies to all services and client applications simultaneously. | ## Migrating watched mail folder options This table contains the equivalent setup in the Conversion Service to migrate your existing 3-­Heights® Document Converter configuration. | 3-­Heights® Document Converter | Conversion Service | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pickup Folder (`-w`) | Input connector: **[Watched Mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** (Exchange Online or IMAP) / [Watched Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#watched-folder) | | Output Folder (`-o`) | Output connector: **[Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder)** / **[Output Mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** (Exchange Online or IMAP) / **[Send Email](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email)** (Exchange Online or SMTP) with **Job Status: Success** and **File Set: Results** | | Succeeded Folder (`-os`) | Output connector: **[Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder)** / **[Output Mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** (Exchange Online or IMAP), **[Send Email](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email)** (Exchange Online or SMTP) with **Job Status: Success** and **File Set: Originals** | | Failed Folder (`-of`) | Output connector: **[Output Folder](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#output-folder)** / **[Output Mailbox](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows)** (Exchange Online or IMAP), **[Send Email](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email)** (Exchange Online or SMTP) with **Job Status: Error** and **File Set: Originals** | | Ignore warnings (`-ow`) | Use condition **Job Status: SuccessOrWarnings** instead of **Success** for output and succeeded folder. | | Job options (`-j`) | Configure workflow and profile settings, see [Job and document options](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#job-and-document-processing) | | Document options (`-b`) | Configure workflow and profile settings, see [Job and document options](https://www.pdf-tools.com/docs/conversion-service/migrate/overview#job-and-document-processing) | ## Job and document options With 3-­Heights® Document Converter, if no job & document options are configured within the Watched Mailbox thread, the configuration from the `O2PMFS.ini` file is taken into account. Otherwise, the job & document options can be set with `-j` `Set Converter Job Options` and `-b` `Set Document Options`: In the Conversion Service, options are _not configured in the Watched Mailbox itself_. A Workflow and Profile needs to be selected in the Configurator when creating or editing your Watched Mailbox configuration. The settings within the selected [Workflow-Profile combination](https://www.pdf-tools.com/docs/conversion-service/workflows/) are taken into account when converting with this Watched Mailbox. | 3-­Heights® Document Converter | Conversion Service | | --------------------------------------------- | ------------------------------------------------ | | | | --- ## Job and document processing options This page provides a list of all equivalent options in the Conversion Service for [application options](#application-options), [job options](#job-options), and [document options](#document-options) when migrating from the 3-Heights® Document Converter. **caution: These tables represent the **current implementation**. The exact conversion process and options used for internal components and external applications may change in future versions without prior notice.** ## Application options | `[*]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `disabled` | Not configurable (automatic) | Applications cannot be disabled, you can disable Office file conversion in the Profile settings if MS Office is not available. | | `Extensions` | Not configurable (automatic) | An optimal conversion process is determined automatically for each file type, workflow, and profile configuration. The association of file types with a specific application cannot be configured explicitly. | | `MaxCallDuration` | Profile setting **Job Settings** -> **Task Timeout** | This setting simultaneously applies to all conversion tasks independent of component/application used for conversion. | | `preload` | Feature not available (`false`) | All external applications are currently loaded on demand. | | `RestartAfterConversions` | Not configurable (~`1000`) | Each worker process and all associated applications are automatically restarted after 1000 conversions, regardless the applications involved. | | `RestrictToExtension` | Not configurable (automatic) | A suitable conversion processes is selected automatically for each file type. | | `WorkingSet` | Not configurable (automatic) | The memory usage of the conversion processes is limited/monitored automatically. | ### MS Word | `[MSWord]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `BFFValidate` | Feature not available (`disable`) | Binary format validation for Word 97-2003 documents is currently not available. | | `BitmapMissingFonts` | Not configurable (`true`) | | | `CreateBookmarks` | Not configurable (`1`) | Bookmarks are always created for Headings. | | `DocStructureTags` | [Archive workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/): Profile setting **Compression and Optimization** (optional) -> **Optimization Profile** [Conversion Workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion): Profile setting **Conversion Settings** -> **Optimize For** | Structure information is always generated *unless* the optimization profile `web`, `max`, `print` or `mrc` is selected or **Optimize For** is set to `Size` | | `EmbeddedDocuments` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments)| | `LockFields` | Feature not available (`false`) | | | `UpdateFieldsAtPrint` | Not applicable | Printing is not used for conversion in the Conversion Service. | | `PW` | Document option **`DOC.PASSWORD`** | Password can only be passed at runtime and cannot be configured statically | | `ShowComments` | Not applicable | Only applies if `SAVEASPDF=false`. See option `SAVEASPDF` | | `SAVEASPDF` | Not configurable (`true`) | The Conversion Service never uses printing and thus always uses the export functionality of MS Word. | | `UseISO19005_1` | Not configurable (`false`) | The built-in PDF/A-1 export of MS Word is not used due to quality issues. | #### Overriding settings in MS Word | `[MSWord]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `PageHeight` | Profile setting **Document Settings** -> **Default Page Size** | This setting simultaneously applies to all non-page based formats such as email or plain text. Limited selection of predefined page sizes available. | | `PageWidth` | Profile setting **Document Settings** -> **Default Page Size** | This setting simultaneously applies to all non-page based formats such as email or plain text. Limited selection of predefined page sizes available. | | `PaperSize` | Profile setting **Document Settings** -> **Default Page Size** | This setting simultaneously applies to all non-page based formats such as email or plain text. Limited selection of predefined page sizes available. | | `PageOrientation` | Not configurable (`0`) | Only Portrait orientation is supported at the moment. | | `PaperMargins` | Profile setting **Document Settings** -> **Default Page Margin** | This setting simultaneously applies to all non-page based formats such as email or plain text. | | `PRINTMARKUPS` | Not configurable (`D`) | | ### MS Excel | `[Excel]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `SAVEASPDF` | Not configurable (`true`) | The Conversion Service never uses printing and thus always uses the export functionality of MS Excel. | | `BFFValidate` | Feature not available (`disable`) | Binary format validation for Excel 97-2003 documents is currently not available. | | `FailPageCount` | Feature not available (`0`) | | | `FitToPage` | Profile setting **Office Conversion** -> **Excel Layout Settings** -> **Allow Scaling** | | | `ForceLetter` | Feature not available (`false`) | | | `MaxPages` | Feature not available (`"all pages"`) | All pages are converted. | | `PrintArea` | Feature not available (` `) | The print area of the original document is used | | `PW` | Document option **`DOC.PASSWORD`** | Password can only be passed at runtime and cannot be configured statically | | `SHEET` | Feature not available | All sheets are converted | | `TIFF.DPI` | Not applicable | This option only applies to conversion using printing | ### MS PowerPoint | `[PowerPoint]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `BFFValidate` | Feature not available (`disable`) | Binary format validation for PowerPoint 97-2003 documents is currently not available. | | `BitmapMissingFonts` | Not configurable (`true`) | | `DocStructureTags` | Archive workflows: Profile setting **Compression and Optimization** (optional) -> **Optimization Profile** Convert to PDF workflow: Profile setting **Conversion Settings** -> **Optimize For** | Structure info is always generated *unless* **Optimization Profile** "web", "max", "print" or "mrc" is selected or "Optimize For" is set to "Size" | | `FitToPage` | Not applicable | The Conversion Service does not use printing for conversion. All slides are exported in their original size. | | `OutputType` | Not configurable (`1`) | PowerPoint presentations are always converted as slides | | `PrintComments` | Not applicable | Only applies if `SAVEASPDF=false`. See option `SAVEASPDF` | | `SAVEASPDF` | Not configurable (`true`) | The Conversion Service never uses printing and thus always uses the export functionality of MS PowerPoint. | | `UseISO19005_1` | Not configurable (`false`) | The built-in PDF/A-1 export of MS Word is not used due to quality issues. | ### MS Visio Conversion of Visio documents is **not supported**. ### MS Outlook **note: Outlook is not used for conversion of MSG files. See [EML](#eml)** | `[Outlook]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `access_grant` | Not applicable | Outlook is not used for conversion of MSG files | | `button_yes` | Not applicable | Outlook is not used for conversion of MSG files | | `OUTLOOKEXE` | Not applicable | Outlook is not used for conversion of MSG files | | `button_yes` | Not applicable | Outlook is not used for conversion of MSG files | | `SKIPFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `SELECTFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `UseHtmlBody` | Not applicable | Outlook is not used for conversion of MSG files | ### MS Project Conversion of MS Project files is **not supported**. ### OpenOffice and LibreOffice Conversion of ODF documents using OpenOffice or LibreOffice is currently **not supported**. ODF documents are converted using MS Word. ### EML | `[EML]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `HeaderTemplate` | Profile setting **Document Settings** -> **Default Language** | The email header cannot be customized except for the language of the labels. | | `Styles` | Feature not available (built-in) | Custom styling of the email header is not supported | | `SELECTFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `SKIPFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `SkipUnusedInline` | Feature not available (`false`) | Inline images that are not referenced in the body are always treated as attachments. | | `DateFormat` | Feature not available | The date format is currently not customizable. | ### TXT2PDF | `[TXT2PDF]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `TEXT.BORDER` | Profile setting **Document Settings** -> **Default Page Margin** | This setting simultaneously applies to all non-page based formats like email or plain text. | | `TEXT.FONTNAME` | Not configurable (Windows: `Calibri`, Linux: `LiberationSans`) | | | `TEXT.FONTSIZE` | Not configurable (`9`) | | | `TEXT.HEIGHT` | Profile setting **Document Settings** -> **Default Page Size** | This setting simultaneously applies to all non-page based formats like email or plain text. | | `TEXT.WIDTH` | Profile setting **Document Settings** -> **Default Page Size** | This setting simultaneously applies to all non-page based formats like email or plain text. | | `TEXT.WRAP` | Not configurable (`true`) | The Conversion Service always wraps lines in plain text documents. | | `TEXT.LANG` | Feature not available | | | `TEXT.TITLE` | Profile setting **Metadata** -> **Title** Job option **`META.TITLE`** | These setting applies to the entire job and set the metadata of the output document. In case of multiple documents per job the effect is not exactly the same. | ### EMF Conversion of Metafiles is **not supported**. ### PDF | `[PDF]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `PDFA-PRECONVERT` | Not configurable (~`true`) | The Conversion Service avoids unnecessary conversions whenever possible. | | `URLPerms` | Not applicable | This setting applies to the conversion of XFA forms in PDF documents using Adobe Acrobat Reader, which is not supported in the Conversion Service. | | `RenderXFA` | Not applicable | This setting applies to the conversion of XFA forms in PDF documents using Adobe Acrobat Reader, which is not supported in the Conversion Service. | ### Image | `[Image]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `IMG2PDF.EXE` | Not applicable / not configurable (~`true`) | All conversion tasks in the Conversion Service are executed in an external worker process, regardless of the file type. However, the img2pdf.exe command line tool is not involved. | | `FitImage` | Profile setting **Document Settings** -> **Default Page Size** Profile setting **Image Settings** -> **Conversion** | The default page size setting also applies to other file formats like email or plain text. | | `Border` | Profile setting **Document Settings** -> **Default Page Margin** | The default page margin setting also applies to other file formats like email or plain text. | | `CMPRQUAL` | Not applicable | Images using lossy compression are not recompressed during conversion. | | `ResolutionDPI` | Feature not available | Resampling of images during conversion is not supported in the Conversion Service. | | `ThresholdDPI` | Feature not available | Resampling of images during conversion is not supported in the Conversion Service. | | `FailSize` | Feature not available | | ### JPM Conversion of JPEG2000 Compound Images is **not supported**. ### XPS Conversion of XPS documents is **not supported**. ### PdfPrinter | `[PdfPrinter]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `Match` | Not applicable | Printing is not used for conversion in the Conversion Service | | `PaperSize` | Profile setting **Document Settings** -> **Default Page Size** | The default page size setting only applies to non-page based file formats like email or plain text. | | `Resolution` | Not applicable | Printing is not used for conversion in the Conversion Service | | `Quality` | Not applicable | Printing is not used for conversion in the Conversion Service | ### TIFFPrinterBW TIFF output format is supported with the TIFF archive workflow. ### TIFFPrinterColor TIFF output format is supported with the TIFF archive workflow. ### HTML | `[HTML]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `IEPRINT` | Not applicable | Neither Internet Explorer nor MS Word are used for HTML conversion | | `HTMLMAXLOADTIME` | Profile setting **Job Settings** -> **Task Timeout** | The task timeout setting simultaneously applies to all conversion tasks, not only HTML conversion | | `PageSetup` | Profile setting **Document Settings** -> **Default Page Size** and **Default Page Margin** | Other than the page size and margin, the page setup cannot be configured | | `HTMOPT` | Not configurable (`true`) | HTML pre-optimization is always executed, the settings used are determined automatically and cannot be configured | ### ZIP | `[ZIP]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `SELECTFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested files and attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `SKIPFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested files and attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `Provider` | Not configurable | A built-in component is used for extraction of ZIP archives | ### PdfOptimize **note: No additional license is necessary to enable optimization in the Conversion Service.** | `[PdfOptimize]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `*` | Not configurable | Optimization profiles are built in and cannot be configured explicitly | | `exepath` | Not configurable | The Conversion Service uses a built-in component for PDF optimization. This also means that optimization cannot be repurposed to implement custom post-processing of the resulting document. | ### Options | `[Options]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `AllowedTransforms` | Feature not available | Custom transforms are not supported in the Conversion Service. | | `MAXTRANSFORMTIME` | Not applicable | Custom transforms are not supported in the Conversion Service. | | `plugins` | Feature not available | Custom plugins are not supported in the Conversion Service. | | `ForceClose` | Not configurable (`true`) | All external applications are terminated on worker process exit. | | `TerminateApps` | Not configurable (`true`) | All external applications are terminated on worker process exit. | ### ACRORD Adobe Acrobat Reader is not used in the conversion process. ### PDFOCR | `[PDFOCR]` | Equivalent setting in Conversion Service | Note | |---|---|---| | `MaxCallDuration` | Profile setting **Job Settings** -> **Job Timeout** and **Task Timeout** | This setting simultaneously applies to all conversion tasks independent of component/application used for conversion. In the Conversion Service, the OCR recognition is split into multiple tasks (per page); in the 3-Heights® Document Converter, the `MaxCallDuration` applies to the recognition of the entire document. The specific timeout values thus cannot be taken as-is. | ## Job options | Option in 3-Heights® Document Converter | Equivalent setting in Conversion Service | Note | |---|---|---| | `ALIVECHECK` | Not applicable | the Conversion Service is licensed by number of cores, not by number of pages. Any normal conversion can be used as "alive check". | | | `CERTNAME` | Profile setting **Digital Signatures** (optional) -> **Signature** -> **Common Name** | This setting only applies to a subset of signature types. | | `COLLCOMP` | Profile setting **Conversion Settings** -> **Collect Mode** | See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `CONVERTALWAYS` | Not configurable (`false`) | the Conversion Service automatically determines whether a conversion is necessary and minimizes the amount of conversions to improve performance | | `EMBEDSOURCE` | *Archive PDF/A-3* workflow: Profile setting **Conversion Settings** -> **Attach Source Document** | | | `ERRSUMMARY` | Not applicable | Error handling works differently in the Conversion Service. See [Errors & Warnings](https://www.pdf-tools.com/docs/conversion-service/migrate/error-handling) | | `ERRPAGE` | Feature not available | Error handling works differently in the Conversion Service See [Errors & Warnings](https://www.pdf-tools.com/docs/conversion-service/migrate/error-handling) | | `FlattenSignatures` | Not configurable (`true`) | The visual part of digital signatures is always preserved. | | `FlattenFormFields` | Not configurable (`false`) | Form fields are preserved unless compression and optimization is enabled with profile "max". | | `FORMAT` | Feature not available (`pdf`) | TIFF output format is supported with the TIFF archive workflow. | | `HTMLPRINTRESOLUTION` | Not applicable | The printing infrastructure is not used by the Conversion Service | | `LINEARIZE` | Feature not available (`false`) | Linearization / Fast web view is **not supported**. | | `MAILHEADER` | Feature not available (`false`) | Including extended email header information is **not supported**. | | `OCR` | Profile setting **OCR Settings** (optional) | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.BITONAL` | Not configurable (automatic) | The service automatically determines the optimal setting for each page. See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.EMBEDBARCODES` | Feature not available (`false`) | Barcode recognition is **not supported**. See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.ENGINE` | Profile setting **OCR Settings** (optional) -> **Engine** | Select type when adding an engine configuration. See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.LANGUAGE` | Profile setting **OCR Settings** (optional) -> **Engine** -> **Languages** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.IMAGEMODE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Image Processing Mode** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.TEXTMODE` | Profile setting **OCR Settings** (optional) -> **Text** -> **Text Processing Mode** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.PAGEMODE` | Profile setting **OCR Settings** (optional) -> **Pages** -> **Page Processing Mode** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.PARAMETERS` | Profile setting **OCR Settings** (optional) -> **Engine** -> **Parameters** or **Predefined Profile** and **Custom Profile** | The configuration settings depend on the chosen type of engine configuration. See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.REEMBEDIMAGE` | Not configurable (`false`) | The original appearance of the document is always preserved. See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.ROTATEPAGE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Correct Rotation** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `OCR.TAGGING` | Profile setting **OCR Settings** (optional) -> **Tagging** -> **Tagging Mode** | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `PASSTHROUGH` | *Workflow Archive as PDF/A-3*: Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | The rule settings only apply to nested documents, not to documents added to the job directly. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `PDFA` | Workflow selection | Whether a PDF/A is produced depends on the selected workflow: `true` -> "Archive as PDF/A-", `false` -> "Convert to PDF". See [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.ERROR` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](https://www.pdf-tools.com/docs/conversion-service/migrate/error-handling) and [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.LOGDETAILS` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](https://www.pdf-tools.com/docs/conversion-service/migrate/error-handling) and [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.LOGSUMMARY` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](https://www.pdf-tools.com/docs/conversion-service/migrate/error-handling) and [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.OCRMODE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Image Processing Mode** | Option `OCR.IMAGEMODE`, See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr) | | `PDFA.EMBEDALLFONTS` | Not configurable (`false`) | | | `PDFA.SUBSET` | Not configurable (`true`) | The use of option `PDFA.SUBSET=false` is strongly discouraged in the 3-Heights® Document Converter | | `PDFA.WARNCOLL` | Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Child Removed** | See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `PDFA.WARNDOWNGRADE` | Not applicable | The desired conformance level cannot be configured explicitly. See [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.WARNUPGRADE` | Not applicable | the Conversion Service never upgrades the file to a different PDF/A standard. See [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.WARNNOTPDFA` | Not configurable (`false`) | The output of the conversion service is always compliant to the requested PDF/A standard. See [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDFA.WARNFONTSUBST` | Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Font Substituted** | | | `PDFA.WARNVISDIFF` | Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Visual Differences** | | | `PDFA.XMPWARNINGS` | Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Metadata Removed** | | | `PDFA.CONVERTEMBPDF` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `PDF.COMPLIANCE` | Workflow selection | The available workflows correspond to the settings `1AB`, `2AUB`, `3AUB` and `PDF`. See [PDF-A and Conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance) | | `PDF.DATE` | The creation date of the input document is used if available | | | `PDF.Embed` | *Prepare Invoice PDF workflow*: Option **`DOC.ROLE`** | The role of each document has to be specified explicitly. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `PDF.Info` | Profile setting **Metadata**. Options **`META.`**. | Only standard info entries can be set. For custom metadata, XMP schemas should be used | | `PDF.InitialView` | Feature not available | | | `PDF.OWNERPASS` | Feature not available | PDF encryption is **not supported**. | | `PDF.PERMISSION` | Feature not available | PDF encryption is **not supported**. | | `PDF.Producer` | Not configurable (built-in) | | | `PDF.USERPASS` | Feature not available | PDF encryption is **not supported**. | | `PDFOPTIMIZE` | Profile setting **Compression and Optimization** (optional) | | | `SIGEMBEDOCSP` | Profile setting **Digital Signatures** (optional) -> **Signature** | Dependent on the type of signature that is selected. | | `SIGFIELDS` | Feature not available | | | `SIGISSUER` | Not applicable | Certificate selection using "Common Name" and "Issuer" is not supported, only by "Fingerprint" | | `SIGPAGE` | Feature not available | Only invisible signatures are supported. | | `SIGPROFILE` | Profile setting **Digital Signatures** (optional) -> **Signature** | No separate configuration file necessary: All settings can be made in the respective signature configuration (type dependent). | | `SIGPROVIDER` | Profile setting **Digital Signatures** (optional) -> **Signature** | There are separate signature types for each available provider. | | `SIGPROXYCRED` | General application setting **Proxy** | This setting applies to all outgoing connections of the service, not just signatures. | | `SIGPROXYURL` | General application setting **Proxy** | This setting applies to all outgoing connections of the service, not just signatures. | | `SIGREASON` | Not configurable (none) | | | `SIGRECT` | Feature not available | Only invisible signatures are supported. | | | `SIGSTORE` | Not configurable (`MY`) | | | `SIGSTORELOCATION` | Not configurable (`1`) | | | `SIGTSCRED` | Profile setting **Digital Signatures** (optional) -> **Signature** -> **TSA** | Only available for certain signature types. | | `SIGTSURL` | Profile setting **Digital Signatures** (optional) -> **Signature** -> **TSA** | Only available for certain signature types. | | `WARNSIGNATURES` | Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Signature Removed** | | | `STAMP` | Profile setting **Stamping** (optional) -> **Stamps** | The stamp configuration differs significantly and cannot be ported 1:1. See [Stamping](https://www.pdf-tools.com/docs/conversion-service/migrate/stamping) | | `TEXTBODY` | Not configurable (`false`) | HTML/RTF body is always used if available. | | `THUMBS` | Feature not available (`false`) | Thumbnail generation is **not supported**. | | `TIFF.BPI` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.COMPR` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.COMPR.BITON` | Archive as TIFF workflow: **Workflows & Profiles** -> **Archive as TIFF** -> **Profile settings** -> **Compression** -> **Bilevel (B&W) Images** | | | `TIFF.COMPR.CONTINOUS` | Archive as TIFF workflow: **Workflows & Profiles** -> **Archive as TIFF** -> **Profile settings** -> **Compression** -> Available options are: RGB and YCbCr ImagesCMYK ImagesImages in LAB Color Space | | | `TIFF.COMPR.INDEXED` | Archive as TIFF workflow: **Workflows & Profiles** -> **Archive as TIFF** -> **Profile settings** -> **Compression** -> **Images with a Color Palette** | | | `TIFF.COMPR.MRC` | Archive as TIFF workflow: **Workflows & Profiles** -> **Archive as TIFF** -> **Profile settings** -> **Compression** -> **Mixed Raster Content (MRC) Compression** | | | `TIFF.COMPR.PDF` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.DITHERINGMODE` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.DPI` | Archive as TIFF workflow: **Workflows & Profiles** -> **Archive as TIFF** -> **Image Settings** -> **Resolution DPI** | | | `TIFF.RENDERINGMODE` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.ROTATE` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.UNPACK` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.XDPI` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `TIFF.YDPI` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `ZIPPED` | Feature not available (`false`) | All workflows produce only PDF output. | | `ZUGFeRDinvoice.xml:ADD` | Feature not available | Embedding of ZUGFeRD electronic invoice data is **not supported**. | | `factur-x.xml:ADD` | Feature not available | Embedding of Factur-X electronic invoice data is **not supported**. | | `#` | Feature not available | Passing documents to the service by file path is not supported | ## Document options | Option in 3-Heights® Document Converter | Equivalent setting in Conversion Service | Note | |---|---|---| | `ADD` | *Prepare Invoice PDF workflow*: Option **`DOC.ROLE`** | See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `ATTACHMENTS:ADD` | Profile setting **Conversion Settings** -> **Collect Mode** -> **Type** -> **Email** | See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `ATT.Name` | REST interface: Multipart header **`Content-Disposion`** | It's not possible to specify different names for `ATT.Name` and `ORIGINALNAME`. See Option `ORIGINALNAME` [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `ATT.Description` | *Prepare Invoice PDF workflow*: Option **`DOC.DESCRIPTION`** | See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `CMPRQUAL` | Not applicable | Images using lossy compression are not recompressed during conversion. | | `CODEPAGE` | Not configurable | UTF-8 and UTF-16 are detected automatically. | | `COLLCOMP` | Profile setting **Conversion Settings** -> **Collect Mode** | Setting cannot be overridden for individual files. [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `FAILFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** Profile setting **Conversion Settings** -> **Warnings** -> **General** -> **Child Removed** | Can only be configured for nested documents (i.e. attachments), not documents that are added to the job directly. See [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `FORCEAPP` | Not configurable | The association of file types with a specific application cannot be configured explicitly. | | `HTZDOCS` | Not applicable | The conversion of website archives is **not supported**. | | `IncludeStructureTags` | Not applicable | The conversion of Visio documents is **not supported**. | | `IncludeDocumentProperties` | Not applicable | The conversion of Visio documents is **not supported**. | | `IncludeBackground` | Not applicable | The conversion of Visio documents is **not supported**. | | `MAILPARTS` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** Watched Mailbox setting **Attachments only** | [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) and [Mail Folders (Watched Mailboxes)](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-mail-folders) | | `ORIGINALNAME` | REST interface: Multipart header **`Content-Disposion`** | | | `AlternateText` | Feature not available | | | `LanguageTag` | Feature not available | | | `Outline` | *Create Dossier PDF workflow*: Profile setting **Outline (Bookmarks)** -> **Document Outline** *Other workflows*: Not configurable (automatic) | [Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments) | | `OutputType` | Not configurable (`1`) | PowerPoint presentations are always converted as slides | | `PRINTCOLOR` | Not applicable | TIFF output format is supported with the TIFF archive workflow. | | `PRINTDM` | Not applicable | The printing infrastructure is not used by the Conversion Service. | | `PW` | Option **`DOC.PASSWORD`** | | | `SAVEASPDF` | Not configurable (`true`) | The Conversion Service never uses printing and thus always uses the export functionality of MS Word. | | `RemoveVBA` | Feature not available (`false`) | Visual Basic macros are not removed from Office documents before conversion, but macros are disabled during conversion to PDF. | | `AcroRdEnableJS` | Not applicable | Conversion of XFA forms in PDF is **not supported**. | | `TIFF.COMPR.BITONAL` | Not configurable (automatic) | | | `TIFF.COMPR.CONTINOUS` | Not configurable (automatic) | | | `TIFF.COMPR.INDEXED` | Not configurable (automatic) | | | `TIFF.COMPR.MRC` | Not configurable (automatic) | | | `TIFF.UNPACK` | Not configurable (automatic) | | | `TRANSFORM` | Feature not available | Custom transforms are not supported in the Conversion Service. | --- ## Nested files and attachments In general, parts of a nested file can be processed in three ways: - Converting the part to the target format. - Using the original part without conversion. - Removing/skipping the part. Depending on the target format, only a subset of those options are allowed. For example, for PDF/A-1 and PDF/A-2, all parts have to be converted or removed. ## Processing individual parts of a nested document In the 3-Heights® Document Converter, the processing of nested files are controlled using the following options: ```ini [Word] EmbeddedFiles=true/false [Excel] EmbeddedFiles=true/false [PowerPoint] EmbeddedFiles=true/false [Embedded] SKIPFILES=... [Outlook] SKIPFILES=... SELECTFILES=... [EML] SKIPFILES=... SELECTFILES=... [ZIP] SKIPFILES=... SELECTFILES=... [Job] PDFA.CONVERTEMBPDF=... PASSTHROUGH=... ``` **note: The option `PASSTHROUGH` in the Document Converter not only applies to nested documents, but also to top-level documents. This behavior cannot be replicated in the Conversion Service where top-level documents are always converted to the target format.** In the Conversion Service, there is a single unified rule-base profile setting. This configuration allows to define a mode for any combination of parent and child document type. Existing rules can be changed and new rules can be added. The setting **Default** at the top applies for all cases that are not covered by an explicit rule. Depending on the workflow, the following 4 modes are available: - **Convert**: The child document is converted to the target format of the workflow (e.g. PDF/A-2). - **Skip**: The child document is removed without a warning. - **Skip with Warning**: The child document is removed and a warning is issued. - **As Is**: The child document is used in the output as-is without conversion. *Note*: Using this mode implies that the resulting document may not be merged together with the rest of the output file. ## Combining all parts of a nested file into a single PDF The 3-Heights® Document Converter generally produces a flat output PDF, i.e. all pages of all parts are merged together to a single big PDF files. The only exceptions are attachments (embedded files) in PDFs which are preserved as such. The only available setting is the job option `COLLCOMP=false`, which can be used to obtain the parts as separate PDF files. **note: This functionality is not available in the Conversion Service, which always produces a single PDF file as output.** The Conversion Service provides much more control over the collection of the individual parts into a single PDF with the profile setting **Collect Mode**: Depending on the workflow and source format, the following modes are available: - **Attach**: The "child" documents are attached to the main PDF as embedded files. - *Note:* This mode is only available for source formats with a single main part, e.g. Emails or Office documents. - **Merge**: The pages of all parts are merged into a single document. - In the case of PDF source files, this mode is called **Flatten** instead of "Merge" to emphasize that the original structure of the PDF is not preserved. - *Note:* Merging the files is not always possible, e.g. if the "Convert Mode" "As Is" is used. In that case the mode is called **Merge or Attach** and the "Attach" mode is used as a fallback. - **Collection (Portfolio) or Single document**: All parts are added to a so called PDF Portfolio, which is a PDF that only acts as a container format for other documents. - *Note:* A Portfolio is only created if the document actually consists of multiple parts. - **Preserve structure**: This mode is exclusively available for PDF source documents to preserve the original structure of the PDF. In case of multiple nesting levels, the setting is applied to each level separately. **Note:** Nested portfolios are always collapsed into a single one. To replicate the behavior of the 3-Heights® Document Converter use the following collect mode settings: - **Merge** or **Merge or Attach** for all file types except PDF. - **Preserve Structure** for PDF. --- ## 3-Heights® OCR Service The Conversion Service can be used with your existing 3-Heights® PDF OCR Service service configuration. A single instance of the 3-Heights® OCR Service can be used by the Conversion Service and other products like the 3-Heights® Document Converter at the same time. The 3-Heights® OCR Service enhances PDF documents using information an OCR engine detects. The optical character recognition (OCR) technology identifies characters in images, scanned documents, and documents containing images with text. It adds a text layer containing recognized characters without visual changes to the original documents. The OCR enables you to make all text extractable. :::warning[Maintenance state of 3-Heights® OCR Service] The 3-Heights® OCR Service is no longer maintained. We recommend configuring the OCR engine using the [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) for new installations. The Pdftools OCR Service is compatible with 3-Heights® OCR Service. For details about the recommended configuration of the OCR engine through the Conversion Service, see [Configure OCR](https://www.pdf-tools.com/docs/conversion-service/configure/ocr/) documentation. --- ## Overview There are several key differences between the Conversion Service and the 3-Heights® Document Converter. ## High-level architecture The general architecture of the Conversion Service is similar to that of the 3-Heights® Document Converter. However, there are some important differences: | | Conversion Service | 3-Heights® Document Converter | | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Main service interface | REST (job-based) | .NET remoting (job-based) | | Web service interface | Built-in REST interface (job-based) Simplified built-in REST interface (single-call, can be combined freely with other integration options). See [Integration](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/) | SOAP interface provided by separate IIS-based web application (single-call) | | Authentication, User management | _No_ built-in solution provided, any available HTTP gateway solution can be used. | Only for Webservice (provided by IIS). Not available for main service interface and thus clients based on it. | | Advanced integration options: Watched Folders, Watched Mailbox, Send Email, single-call web service, Execute Command, etc. | Provided by the single separate service "Conversion Service Connections" and can be combined freely. See [Integration](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/) | Provided by several separate services ("Watched Folder Service", "Mail Folder Service", etc) and cannot be combined with each other. | | Client applications (GUI, Command Line, Office Add-ins, etc.) | Available as a separate installer. [Microsoft Office integration](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/office-integration), [GUI Client](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client), [Command Line Client](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/CLI) | Available as a separate installer. | | Linux/Docker image | [Supported](https://www.pdf-tools.com/docs/conversion-service/update/), but with reduced feature set. | Not supported | | Worker process isolation | Workers are running as normal separate processes in the same session. All processing tasks are executed in a worker process without exception. | Workers are running as separate RDP sessions. Only Office conversions are executed in worker sessions. | ## Job and document processing While the 3-Heights® Document Converter configuration specified **how a conversion is performed**, allowing you to configure each application or component explicitly, in the Conversion Service, the configuration specifies **what the expected result should be**. The applications and components selected and configured are determined automatically to produce the best possible result. The Document Converter offered simple key-value pairs throughout all tiers of configuration: _application options_, _job options_, and _document options_. The Conversion Service uses different levels of flexibility and complexity for each configuration tier: - **Workflow**: A workflow represents a broad use case and defines the general conversion process. Workflows are tailored to a specific use case, which is also reflected in the available configuration settings. All workflows are provided by the application and cannot be changed by the user or operator. - **Profile**: A profile is a structured, workflow-specific set of configuration settings. Each workflow can have an arbitrary number of profiles which can be selected at runtime. Profiles are statically configured in the service and cannot be created dynamically at runtime. - **Job and document options**: Job options and document options are used to refine certain aspects of a profile at runtime and to provide document or job-specific data to the conversion. Job options and document options are simple key-value pairs and don't provide the full flexibility available in the profile configuration. If a certain configuration aspect cannot be controlled by these options, a separate profile configuration is necessary. In the 3-Heights® the Document Converter, job options specified the output format and processing steps performed on the output file. However, due to the lack of workflows and profiles in the 3-Heights® Document Converter, job options and document options could override almost any of the available configuration settings. With the Conversion Service, the **output format is determined by the selected workflow** and optional processing steps can be configured in the profile configuration. The workflows available in the Conversion Service are roughly equivalent to the configuration options `FORMAT`, `PDFA` and `PDF.COMPLIANCE`, configured at application or job level. Document options are similar in both products from a technical perspective, however, only a few select workflow-specific document options are available in the Conversion Service. Application options in the 3-Heights® Document Converter meant that file types could be explicitly associated with an application/component. Each application/component could be configured individually on a low-level basis. Only a single set of static options could be configured in the service itself, but each option could be overridden at runtime. In the Conversion Service, profile settings allow you to **configure the expected result by file type**. Applications/components are selected and configured automatically. The Conversion Service is designed to seek a balance between flexibility and complexity, facilitating configuration and setup. | Tier in 3-Heights® Document Converter | Equivalent in Conversion Service | | ------------------------------------------------------------- | ----------------------------------------------------------- | | [Application options](https://www.pdf-tools.com/docs/conversion-service/migrate/job-processing#application-options) | [Profile settings](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) | | [Job options](https://www.pdf-tools.com/docs/conversion-service/migrate/job-processing#job-options) | [Profile configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) | | [Document options](https://www.pdf-tools.com/docs/conversion-service/migrate/job-processing#document-options) | [Workflow-specific document options](https://www.pdf-tools.com/docs/conversion-service/workflows/) | ## Feature compatibility between products Feature compatibility between the Conversion Service and the 3-Heights® Document Converter is indicated according to three levels: - **Yes**: The feature is supported in a way that most use cases are covered. This does not mean that it supports exactly the same configuration options. It is not guaranteed that the services will behave exactly the same in every single case. You can expect some differences. - **Partially**: The feature is generally available, but there are notable differences in a way that prohibits a straightforward migration in many cases. - **No**: The feature is not supported. | Feature | Conversion Service | 3-Heights® Document Converter | Notes | | ------------------------------------------------ | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Processing of embedded files / Attachments | _Yes_ | _Partially_ | Flexible support for processing embedded files and attachments across all supported file formats. See [Nested files and attachments](#supported-nested-files-and-attachments) | | OCR (Text recognition) | _Yes_ | _Yes_ | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr). | | OCR (Barcode recognition) | _No_ | _Yes_ | See [OCR](https://www.pdf-tools.com/docs/conversion-service/migrate/ocr). | | Digital signatures | _Yes_ | _Yes_ | | | PDF compression and optimization | _Yes_ | _Yes_ | Only predefined profiles supported. | | PDF linearization (fast web-view) | _Yes_ | _Yes_ | | | Stamping | _Partially_ | _Yes_ | See [Stamping](https://www.pdf-tools.com/docs/conversion-service/migrate/stamping). | | Metadata | _Yes_ | _Yes_ | | | Electronic invoice embedding (ZUGFeRD, Factur-X) | _No_ | _Yes_ | | | Table of contents and title page generation | _Yes_ | _No_ | See [Create Dossier PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier). | | Custom plugins and transformations | _No_ | _Yes_ | | ### Supported input formats The table shows the input formats supported by the Conversion Service and those originally supported by the 3-Heights® Document Converter. | Format | Conversion Service | 3-Heights® Document Converter | Notes | | ----------------------------------------------------------------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PDF | _Yes_ | _Yes_ | | | PDF with XFA forms (Adobe Lifecycle) | _No_ | _Yes_ | XFA is a proprietary format and was deprecated in PDF 2.0. | | Raster image formats (JPEG, PNG, GIF, TIFF, BMP, JBIG2, JPEG2000, HEIC, HEIF) | _Yes_ | _Yes_ | | | JPEG2000 compound image (JPM) | _No_ | _Yes_ | | | WebP (raster image format supported by the Conversion Service) | _Yes_ | _No_ | | MS Word binary formats (DOC, DOT) | _Yes_ | _Yes_ | Requires MS Word installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS Word OOXML-based formats (DOCX, DOCM, DOTX, DOTM) | _Yes_ | _Yes_ | Requires MS Word installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | WordML / WordprocessingML (XML) | _Yes_ | _Yes_ | Requires MS Word installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS Excel binary formats (XLS, XLT) | _Yes_ | _Yes_ | Requires MS Excel installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS Excel OOXML-based formats (XLSX, XLSM, XLTX, XLTM) | _Yes_ | _Yes_ | Requires MS Excel installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | SpreadsheetML (XML) | _Yes_ | _Yes_ | Requires MS Excel installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS PowerPoint binary formats (PPT, PPS) | _Yes_ | _Yes_ | Requires MS PowerPoint installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS PowerPoint OOXML-based formats (PPTX, PPTM, PPSX, PPSM) | _Yes_ | _Yes_ | Requires MS PowerPoint installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | MS Project | _No_ | _Yes_ | | | MS Visio | _No_ | _Yes_ | | | Open Document Text (ODT) | _Yes_ | _Yes_ | Requires MS Word installed and properly licensed on the server. OpenOffice or LibreOffice are not supported. | | Open Document Spreadsheet (ODS) | _Yes_ | _Yes_ | Requires MS Excel installed and properly licensed on the server. OpenOffice or LibreOffice are not supported. | | Open Document Presentation (ODP) | _Yes_ | _Yes_ | Requires MS PowerPoint installed and properly licensed on the server. OpenOffice or LibreOffice are not supported. | | MIME-email (EML) | _Yes_ | _Yes_ | | | Outlook-email (MSG) | _Yes_ | _Yes_ | | | ZIP archive | _Yes_ | _Yes_ | | | RAR-Archive | _No_ | _Yes_ | | | Plain text (TXT) | _Yes_ | _Yes_ | | | Rich text (RTF) | _Yes_ | _Yes_ | Requires MS Word installed and properly licensed on the server. See [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion). | | Comma-separated values (CSV) | _Yes_ | _Yes_ | | | Document-like HTML | _Yes_ | _No_ | Self-contained single-page HTML intended for page layout. All media and styles have to be inline or referenced by absolute URL from a location accessible by the service. | | Website-Archive (MHT, HTMZIP) | _No_ | _Yes_ | | | URL | _Partially_ | _Yes_ | URL as a file format is not supported; however, the REST interface allows converting files by URL. | | Metafile (EMF) | _No_ | _Yes_ | | | XPS | _No_ | _Yes_ | | | Custom formats (Plugins) | _No_ | _Yes_ | | ### Supported output formats The Conversion Service converts [input files](#supported-input-formats) to PDF format, either as PDF 1.x, or PDF/A conformant files (PDF/A-1, PDF/A-2, PDF/A-3) depending on the workflow used. | Format | Conversion Service | 3-Heights® Document Converter | Notes | | --------------- | ------------------ | ----------------------------- | ----------------------------------------------------- | | PDF/A-1 | _Yes_ | _Yes_ | See [PDF/A and conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance). | | PDF/A-2 | _Yes_ | _Yes_ | See [PDF/A and conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance). | | PDF/A-3 | _Yes_ | _Yes_ | See [PDF/A and conformance](https://www.pdf-tools.com/docs/conversion-service/migrate/pdfa-conformance). | | Plain PDF (1.x) | _Yes_ | _Yes_ | See [Convert to PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion). | | TIFF | _Yes_ | _Yes_ | See [Archive as TIFF](https://www.pdf-tools.com/docs/conversion-service/workflows/tiff). | ### Supported nested files and attachments The table below lists the supported file types and attachments for the 3-Heights® Document Converter and the Conversion Service. | Type | Conversion Service | 3-Heights® Document Converter | | --------------------------------------------------- | ------------------ | ----------------------------- | | Files in ZIP archive | _Yes_ | _Yes_ | | Files in RAR archive | _No_ | _Yes_ | | Attachments of MIME-email (EML) | _Yes_ | _Yes_ | | Attachments of Outook-email (MSG) | _Yes_ | _Yes_ | | Attachments (embedded files) in PDF file | _Yes_ | Only PDF to PDF/A | | File attachment annotations in PDF file | _Yes_ | Only PDF to PDF/A | | Files in PDF portfolio | _Yes_ | Only PDF to PDF/A | | Attachments in OOXML-based Word file (DOCX) | _Yes_ | _Yes_ | | Attachments in classic binary Word file (DOC) | _No_ | _Yes_ | | Attachments in OOXML-based Excel file (XLSX) | _Yes_ | _Yes_ | | Attachments in classic binary Excel file (XLS) | _No_ | _Yes_ | | Attachments in OOXML-based PowerPoint file (PPTX) | _Yes_ | _Yes_ | | Attachments in classic binary PowerPoint file (PPT) | _No_ | _Yes_ | For more on how nested files and attachments are handled, see [Nested files and attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments). ## Integrations The Conversion Service offers multiple integration options such as, [watched folders](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/) and other connectors, a [REST API](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api), and a [PDF GUI client](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client). | Integration | Conversion Service | 3-Heights® Document Converter | | ---------------------------------------------------------- | ----------------------- | ----------------------------- | | [GUI client application](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client) | _Yes_ | _Yes_ | | [Command line client application](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/CLI) | _Yes_ | _Yes_ | | [Watched folders](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-folders) | _Yes_ | _Yes_ | | [Mail folders](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-mail-folders) | _Yes_ | _Yes_ | | [Send email](https://www.pdf-tools.com/docs/conversion-service/migrate/integrate/watched-mail-folders) | _Yes_ | _Yes_ | | [Web service interface (REST)](https://www.pdf-tools.com/docs/conversion-service/integrate/rest-api) | _Yes_ | _No_ | | Web service interface (SOAP) | _No_ | _Yes_ | | Client library | _No_ | _Yes_ | | MS Office add-in | _Yes_ | _Yes_ | | Windows Explorer extension | _No_ | _Yes_ | | [Docker image](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container) | _Partial_ [^1] | _No_ | [^1]: The Docker image does not support all features. In particular, it does not support any of the integration options. --- ## PDF/A and conformance In the Conversion Service, there are four separate workflows to convert files to PDF depending on the required standard: - [**PDF/A-2**](#pdfa-2): Archive as PDF/A-2 (default workflow) - [**PDF/A-3**](#pdfa-3): Archive as PDF/A-3 - [**PDF/A-1**](#pdfa-1): Archive as PDF/A-1 (disabled by default) - [**Plain PDF 1.X**](#plain-pdf-1x): Convert to PDF The settings available for all four workflows are similar, but there are certain differences reflecting the specific capabilities and use cases of each of those standards. **tip: For more about the steps in each workflow, see [Archive PDF/A workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/#archive-as-pdfa-workflows).** ## Conformance levels The Conversion Service does **not allow you to select the specific conformance *level* explicitly** (e.g. PDF/A-2**u**). The optimal level is determined automatically by the service. The output PDF always has the best level that can be achieved with the provided input document and configuration. ## PDF/A-2 Selecting the **[Archive PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2)** workflow is equivalent to setting the following options in the 3-Heights® Document Converter: ```ini FORMAT=PDF PDFA=TRUE PDF.COMPLIANCE=2AUB ``` PDF/A-2 is the recommended standard for archiving documents. The workflow is specifically tailored to the use case of document archiving, focusing on: - Maintaining the original appearance and structure of the document. - Minimizing information loss. - Ensuring traceability and reproducibility of the changes made to the document. ### Handling nested files The PDF/A-2 standard allows a document to contain attachments (embedded files) under the condition that those are also valid PDF/A-1 or PDF/A-2 files. For this reason, the *default* profile of this workflow is configured in a way that the output PDF mirrors the structure of the original document as closely as possible: - Files in a ZIP archive are converted to PDF/A-2 (if possible) and combined into a PDF portfolio (Collection). - Email attachments are converted to PDF/A-2 (if possible), and added as attachments to the PDF containing the email body. - Files already embedded in a PDF are converted to PDF/A-2 if possible, preserving the original structure of the PDF. - Attachments of Office files are converted to PDF/A-2 (if possible) and added as attachments the main PDF. **note: These settings **can be changed for each file type** in the profile settings to create an output closer to that of 3-Heights® Document Converter.** See **[Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments)**. ### Quality control and traceability - Each major step of the conversion process is visible in the event list available at the REST interface. - Critical changes to the document are visible in the event list with severity "warning". - Specific types of critical changes can be prohibited in the profile configuration section, **Conversion Settings** -> **Warnings**. ## PDF/A-3 Selecting the **[Archive PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3)** workflow is equivalent to setting the following options in the 3-Heights® Document Converter: ```ini FORMAT=PDF PDFA=TRUE PDF.COMPLIANCE=3AUB ``` The PDF/A-3 standard is very similar to the PDF/A-2 standard. However, in addition, it allows attachments that are not conforming to PDF/A. This allows for more flexibility but also requires more care to ensure that result is still safe for archiving. For this reason, PDF/A-3 should only be used in certain use cases where PDF/A-2 is not sufficient: - The workflow allows to embed the unconverted original file as "Source" into the converted PDF. This allows to preserve the original file while still ensuring that the document is archive-ready. This can be configured for each file type in the profile configuration section **Conversion Settings** -> **Attach source file**. This setting corresponds to the option `EMBEDSOURCE` in the 3-Heights® Document Converter. - The workflows allows to exclude certain nested file types from conversion and include the original instead: In the profile section **Conversion Settings** -> **Convert Mode for Child Documents**, the additional mode "As Is" is available. **note: Such unconverted attachments are generally **not safe for archiving** because they don't comply to any of the PDF/A standards.** See **[Nested Files & Attachments](https://www.pdf-tools.com/docs/conversion-service/migrate/nested-files-attachments)**. ## PDF/A-1 Selecting the **[Archive as PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1)** workflow is equivalent to setting the following options in the 3-Heights® Document Converter: ```ini FORMAT=PDF PDFA=TRUE PDF.COMPLIANCE=1AB ``` This workflow is disabled by default. You can enable it explicitly in the **Workflows & Profiles** view. If possible, use the newer and improved PDF/A-2 standard instead. The following restrictions apply to PDF/A-1: - The PDF/A-1 standard **does not support attachments (embedded files)**. The structure of nested input files cannot be preserved. All pages of all documents are combined into a single large PDF. For that reason, the only supported value in the **Collect Mode** configuration is *Merge* (or *"*Flatten* in case of PDFs). - The PDF/A-1 standard **does not support transparency**. During conversion, transparency has to removed, which results in a warning. - The PDF/A-1 standard **does not support layers (optional content)**. Layers are removed during conversion, which results in a warning. ## Plain PDF 1.X Selecting the workflow **[Convert to PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion)** is equivalent to setting the following options in the 3-Heights® Document Converter: ```ini FORMAT=PDF PDFA=FALSE ``` This workflow produces a PDF that is *not* compliant to any of the above PDF/A standards. In contrast to the PDF/A workflows, this workflow focuses less on quality/reproducibility and instead more on conversion speed and file size. The priority can be selected in the profile configuration section **Conversion Settings** -> **Optimize For** by selecting *Speed* or *Size*. Other than that, the settings are similar to those of the [Archive PDF/A-3](#pdfa-3) workflow. --- ## Stamping Compared to the 3-Heights® Document Converter, stamping in the Conversion Service is much simpler: - The functionality is more limited, while still covering the most common use cases. - The configuration is easier to understand: no separate stamp configuration file is needed. This means that for many existing stamp configurations, a one-to-one migration is not possible, but often a similar result can be achieved. For more about stamping in the Conversion Service, see [Configure stamping](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping). | Content Type | Conversion Service | 3-Heights® Document Converter | |---|---|---| | Text | Yes | Yes | | Images | Yes | Yes | | Shapes | No | Yes | | Barcodes | Yes | Via image URL | | Links | No | Yes | | Compound content | No | Yes | ## Document-level configuration While the 3-Heights® Document Converter provides many options to configure the stamps on a document level, the Conversion Service can only apply stamps as page content on the first page of the document, the last page, or all pages. | Feature | Conversion Service | 3-Heights® Document Converter | |---------|--------------------|-------------------------------| | Apply as foreground content | Yes | Yes | | Apply as background content | No | Yes | | Apply as PDF annotation | Yes | Yes | | Apply as layer (optional content) | No | Yes | | Page selection | No | Yes | | Modify existing stamp | No | Yes | **note: In the Conversion Service, annotations are added as part of the Stamp and Annotation processing step.** ## Layout configuration The 3-Heights® Document Converter provides separate configuration settings for position and alignment that can be combined arbitrarily. In the Conversion Service, the position and alignment of a stamp are linked: if the position is specified as a distance to a specific page border, the alignment is automatically chosen accordingly. For example, if the position is specified relative to the right and top border, the stamp is also aligned to the right and top. | Feature | Conversion Service | 3-Heights® Document Converter | |---|---|---| | Position relative to borders | Yes | Yes | | Alignment | Tied to relative position | Yes | | Auto-detect page orientation | No | Yes | | Scale relative to page size | No | Yes | | Clip to size | No | Yes | | Rotation | Only for text | Yes | | Arbitrary transformation | No | Yes | | Transparency / opacity | Only for text | Yes | ## Text configuration Both the 3-Heights® Document Converter and the Conversion Service provide configuration settings to determine the [style](#text-style) and [text variables](#variable-text). ### Text style | Feature | Conversion Service | 3-Heights® Document Converter | |---|---|---| | Font family & style | Yes | Yes | | Size | Yes | Yes | | Color | Yes | Yes | | Transparency / opacity | Yes | For entire stamp | | Stroke (outline) | No | Yes | | Underline | No | Yes | | Multiple styles | No | Yes | ### Variable text The 3-Heights® Document Converter supports two kinds of placeholders: - Predefined placeholders using the syntax `{PLACEHOLDERNAME}` are available only for the actual text value. - Custom placeholders using the syntax `[[PLACEHOLDERNAME]]` can be used to provide runtime data for any parts of the stamp XML configuration. The Conversion Service uses a unified placeholder syntax for both predefined and custom placeholders: - `[input:PLACEHOLDERNAME]` for placeholders referencing data from converted file (e.g. `[input:TITLE]`). - `[custom:PLACEHOLDERNAME]` for custom placeholders. Both are only applicable to the actual text value of the stamp, not to other properties like position or alignment. | Feature | Conversion Service | 3-Heights® Document Converter | |---|---|---| | Standard PDF metadata placeholders | Only title | Yes | | Date & time placeholders | No | Yes | | Page number & count placeholders | Only in Create Dossier PDF workflow | Yes | | Custom placeholders | Yes | Yes | ## Image configuration Both the 3-Heights® Document Converter and the Conversion Service provide configuration settings to determine [variable image content](#variable-image-content). In the Document Converter, the variable image content was often used to dynamically create barcode images. Barcodes are natively supported by the Conversion Service using the [Barcode stamp type](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping), which directly accepts the barcode data. It's no longer necessary to create the image on the client side. | Feature | Conversion Service | 3-Heights® Document Converter | |---|---|---| | Local path | Yes | Yes | | URL | No | Yes | | URL / path placeholder | No | Yes | | Automatic aspect ratio | Yes | No | ### Variable image content The 3-Heights® Document Converter supports variable content by using the general placeholder syntax to supply the image URL at runtime, e.g ``. Variable image data is not supported by the Document Converter in the general case. --- ## Monitor the service The Conversion Service provides [service logs](https://www.pdf-tools.com/docs/conversion-service/monitor/service-log) to monitor the status and performance of the service. You can also use the Conversion Service Configurator to supervise document processing via **[Health & activity](https://www.pdf-tools.com/docs/conversion-service/monitor/health-activity)** and **[Statistics](https://www.pdf-tools.com/docs/conversion-service/monitor/statistics)** tabs. For distributed tracing and observability, the Conversion Service supports **[OpenTelemetry (OTLP)](https://www.pdf-tools.com/docs/conversion-service/monitor/opentelemetry)** to export traces, logs, and metrics to backends such as Grafana, Datadog, or Seq. --- ## Health & Activity The state and recent activity of the service is monitored by the Health and activity tab of the Conversion Service Configurator GUI, which is added to the Windows start menu during installation. The purpose is to provide an overview of the service's performance. It consists of the following parts: - The number of jobs that the service is currently processing - Time passed since when the service was started - Validity of the license - Pie chart about the results of the jobs processed on the current day - Time chart tracking the service's load and performance ## Jobs, tasks, and parallel execution A job is the unit that is sent to and processed by the Conversion Service. A job consists of input documents, a workflow name, a profile name, and an output path. Depending on the job content, a set of processing steps is required to complete its execution (such as destructuring, conversion, merging, etc). A task is the execution unit of such a processing step. Tasks are generally executed in parallel and tasks are held in a queue in case the service is charged to capacity. The parallel processing capacity of the service depends on the license and the underlying hardware system. The license and hardware limit the number of tasks that can be processed in parallel by the service. This number is referred to as the maximum number of concurrent tasks (*maxConcurrentTasks*). ### Status Summarizes the status of the Conversion Service by displaying the count of currently processed jobs, status of the license, and service uptime. ### Processed jobs The pie chart summarizes and monitors jobs processed during the current day in the following categories: - **Jobs successful**: Jobs converted successfully. - **Jobs with warnings**: Jobs converted with warnings. - **Jobs failed**: Jobs that failed with errors related to the input document. For example, *Corrupt*, *UnsupportedFormat* or *Generic*. - **Jobs with errors**: Jobs that failed due to a *Timeout*, *Configuration* or *Internal* error. - **Jobs canceled**: Jobs that were canceled by the user. ### Activity The time chart gives an indication on the service's load and performance. It displays the following two curves, which are limited by the parallel processing capacity of the service: - **Utilization** (green): Plots the percentage of processing capability used. The total possible processing capability of the service depends on your license and your system. - **Number of tasks in queue** (yellow): Shows the number of tasks waiting in the queue to be processed. On top of the diagram, on the very right, there are four numbers, each next to a symbol. These values are in the color of the curve they are associated with. The top green value is the maximum. The bottom green value is the average of the utilization. The top yellow value is the maximum number of tasks in queue for the selected time span. The bottom yellow value is the average time a task spends waiting in the queue before being processed. Next to the Activity heading, the following time spans can be configured for the chart: - Last ten minutes - Last hour - Last two hours - Last four hours When you change the selected item in the legend at the bottom of the chart, the curve it represents is brought to the foreground together with its associated grid for easier reading. Note that for the Y-axis, the range of values is labeled on the right side. --- ## OpenTelemetry (OTLP) The Conversion Service supports [OpenTelemetry](https://opentelemetry.io/), an open standard for exporting traces, logs, and metrics to observability backends such as Grafana, Datadog, Jaeger, or Seq. ## Configuration To enable OpenTelemetry, set environment variables on the host machine (Windows) or in the container configuration (Docker). ### Environment variables | Variable | Description | Example | |----------|-------------|---------| | `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry Protocol (OTLP) collector endpoint (required) | `http://localhost:4317` | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Export protocol: `grpc` (default) or `http/protobuf` | `grpc` | | `OTEL_SERVICE_NAME` | Service name shown in traces and logs | `Conversion Service` | | `OTEL_RESOURCE_ATTRIBUTES` | Additional resource attributes | `service.instance.id=node-1` | When you set `OTEL_EXPORTER_OTLP_ENDPOINT`, the service exports telemetry data using the specified protocol (gRPC by default). For the complete list of environment variables, see the [OpenTelemetry SDK Environment Variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/). ### Examples **Windows:** Set system environment variables or configure them in the service settings: ```powershell $env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4317" $env:OTEL_SERVICE_NAME = "Conversion Service" ``` **Docker:** ```bash docker run -d \ -p 13033:13033 \ -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \ -e OTEL_SERVICE_NAME="Conversion Service" \ pdftoolsag/conversion-service:6 ``` ### Cluster deployments When you deploy Conversion Service across a cluster with more than one instance, use `OTEL_SERVICE_NAME` or `OTEL_RESOURCE_ATTRIBUTES` to identify each instance: ```bash # Option 1: Unique service name per instance -e OTEL_SERVICE_NAME="Conversion Service (Node 1)" # Option 2: Use resource attributes -e OTEL_SERVICE_NAME="Conversion Service" -e OTEL_RESOURCE_ATTRIBUTES="service.instance.id=node-1,deployment.environment=production" ``` ## Telemetry data When enabled, the service exports: | Type | Description | |------|-------------| | **Traces** | Request flow through the service with timing for each operation | | **Logs** | Service logs with trace correlation (`trace_id`, `span_id`) | | **Metrics** | Runtime metrics: requests, duration, errors | The service correlates traces and logs by trace ID, so you can navigate from a trace to its related log entries in supported backends. ## Verify your configuration To confirm OpenTelemetry is working: 1. Start the Conversion Service with the environment variables configured. 1. Send a conversion request using the API, a connector, or the [Conversion Service Client](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client). 1. Check your observability backend for incoming data: - **Traces**: Look for spans with the service name you configured. - **Logs**: Verify log entries include `trace_id` and `span_id` fields. 1. In the service logs, confirm there are no connection errors to the OTLP endpoint. If telemetry data doesn't appear, verify that: - The `OTEL_EXPORTER_OTLP_ENDPOINT` URL is reachable from the service. - The configured protocol (`grpc` or `http/protobuf`) matches your collector configuration. - Your firewall allows outbound connections to the collector port (default: 4317 for gRPC, 4318 for HTTP). ## Learn more For more information about OpenTelemetry, refer to the following external resources: - [OpenTelemetry documentation](https://opentelemetry.io/docs/) - [OTLP specification and protocol details](https://opentelemetry.io/docs/specs/otlp/) - [List of OpenTelemetry-compatible vendors and backends](https://opentelemetry.io/ecosystem/vendors/) --- ## Service log The Conversion Service writes verbose information to a log file (or to the standard output in the case of Docker container). This allows the administrator to monitor the service's operation and troubleshoot problems after an event. ### Location of the log file **Windows:** The location of the standard log files can be configured using the [Service configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service). The name of the log files is `ConversionService-Service.log`. After each day, the old log file is compressed and moved to the file `ConversionService-Service-yyyy-mm-dd.log.zip`. A maximum of 90 archived log files are kept. **Docker:** The file containing all log entries is `/var/log/convsrv/ConversionService-Service.log`. This log file is primarily designed for [support issues](#creating-a-support-request-using-the-service-logs). **Example**: See all critical errors that occurred in container `‹CONTAINER›` ``` docker exec ‹CONTAINER› grep -e ",ERROR\|FATAL," /var/log/(*@\ctxDockerFolder @*)/(*@\ctxServiceShortName @*)-Service.log ``` ### Log properties In addition to standard properties, log entries contain the following: | Property | Description | |---|---| | `Level` | Severity of the message. See [Severity level](#severity-level). | | `Process name` | The name or type of the process in which the log event occurred. | | `Message` | The log message. | | `Exception` | Critical log messages often have an exception associated that contains more detailed information on the message's cause. | | `Job ID` | Using the job ID, all messages of a particular processing job can be filtered for analysis. | | `Task ID` | This is an internal ID used by the service, which is useful for analysis by Pdftools Support team. | | `Remote ID` | The IP address of the remote host (client). This is meaningful only for messages that are associated with a request at the REST API. | #### Severity level The level indicates the severity of the message. The following severities are common: | Level | Description | |---|---| | `Fatal` | Severe error. See **Error** below. | | `Error` | Error that prevents the service from operating, e.g. because of an incomplete installation or invalid configuration. Clients sending processing requests to the service receive an error code *internal* or *configuration*. It is recommended that the service administrator be notified whenever a message of severity level **Error** or higher occurs. This can be achieved by monitoring the standard service log file or creating a [custom log](#custom-logs). | | `Warn` | Errors that are not critical and do not prevent the service from operating. Even though no immediate action by the service administrator is required, it is advisable to review warnings periodically and decide if an action is required. | | `Info` | Informational events are useful to monitor the service's operation. | | `Debug` | Debug and tracing messages are strictly for development purposes and analysis by the Pdftools Support team. During productive use of the service, messages of this level should be disabled for performance reasons. | | `Trace` | See **Debug** above. | ### Reading the log file The standard log file is in CSV format, which can be opened in several applications. Many of them offer a tabular view of CSV files, highlighting by log message severity, and filtering. ## Custom logs **Windows:** For logging, the Conversion Service uses [NLog](https://nlog-project.org/), a very flexible logging platform. This allows to create additional log outputs. For example, to write to a database or the Windows Event Log. ### Layout renderers The following additional layout renderers are available in the Conversion Service: - `${gdc:processName}`: Process name - `${mdlc:jobId}`: Job ID - `${mdlc:taskId}`: Task ID - `${mdlc:remote-ip}`: Remote IP For more information on these properties, see [Log properties](#log-properties). #### Examples of layout renderers To add a new log output, a file `NLog.config` can be created in the directory `bin` of the installation directory. For more information, see [NLog](https://nlog-project.org/) documentation. **note: A new logging configuration can be tested by disabling the Conversion Service's license in the license manager. When the service is restarted and a job scheduled, an error is logged.** More information on logging configuration issues can be obtained by activating internal logging: ```xml ``` **Example**: A `NLog.config` that writes critical messages to the Windows Event Log ```xml ``` **Example**: A `NLog.config` that sends critical messages by email ```xml ``` **Docker:** For logging, the Conversion Service uses [NLog](https://nlog-project.org/), a very flexible logging platform. This allows to create additional log outputs. For example, to write to Amazon CloudWatch or Google Cloud Platform Logs. ## Creating a support request using the service logs When you create a support request, you need to provide Pdftools Support with information to effectively evaluate and troubleshoot your support case. You can automatically export the service logs and other information using the Configurator. The **Support Request** tab in the Configurator lets you generate a ZIP file ("SupportRequestFiles") in your local machine that you can attach to your support request. The ZIP file contains data such as active workflows, jobs recently performed by the service, service log files, and service debug log files that help us to identify the origin of your issue, and perform troubleshooting. To generate the ZIP file with all the required information, activate the **Support Data** toggle. To include information about the security policy of users and groups which helps to identify Microsoft Office related issues, activate the **Extended Support Data** toggle. You can also choose to share analytics to help improve the product. Pdftools does not track any of the data of your Conversion Service implementation. Analytics are only used for the purposes of improving your experience with the Conversion Service. The exported analytics ZIP file contains statistics on the workflows and profiles used, the number of output files and their size, and the number of pages in each output file. No information that can be used to identify the contents of the documents you process is collected. All analytics are stored in your local machine. You can choose to include analytics data when you create the ZIP file for your support request by activating the **Analytics data** toggle. When you click **Export**, a window opens where you can choose where to save the exported file. You must attach this file to your support request. ### Support Data Collection We collect specific data from your system to help us diagnose and address your issues more effectively. This collection is vital for us to provide you with the best possible support. Our commitment is to maintain transparency with our enterprise clients about the data we access. **Data We Collect:** 1. **Event Logs in the Last 24h**: This helps us understand any recent system or application events that might have contributed to the issue you're facing. 2. **Software Versions**: - **Conversion Service**: Helps us determine if any known issues exist with your current version. - **Office**: Assists in diagnosing potential compatibility or integration issues. 3. **Win32 Tables**: - **UserAccount, LogonSession, LoggedOnUser**: Provides insights into user accounts, their sessions, and logon activities. - **Group, GroupUser**: Details about user groups and their members that are necessary for understanding access and permissions. The Conversion Service collects this data only if you enable the **Extended Support Data** toggle. - **Service**: Information about running services, which can highlight conflicts or dependencies. - **Printer, PrinterDriver**: Essential for understanding the PDF generation process. When creating PDFs from Excel spreadsheets, Excel uses the Windows printing system, making printer settings and drivers crucial for successful conversion. - **QuickFixEngineering**: Information on recent patches or fixes applied to the system. - **GPO Information**: Extracts rights for all Users and Groups, assisting in understanding policy-related issues. - **OperatingSystem**: Details of the OS, which can help in understanding compatibility or known issues. - **ComputerSystem**: Information about the computer's hardware and configuration. - **Processor**: Helps diagnose performance or compatibility issues. - **LogicalDisk**: Information on storage, which can aid in understanding space-related issues. - **DCOMApplication, DCOMApplicationSetting**: Provides insights into distributed component settings and potential conflicts. 4. **Conversion Service Product Configuration**: - **appsettings.json**: Configuration settings that might be causing issues. - **Workflows.xml**: Workflow configurations that could lead to operational problems. - **Backups of old Workflows.xml**: Historical configurations to compare and trace the origin of issues. 5. **Log Files (from the Conversion Service)**: Detailed logs can highlight errors, warnings, or unusual behaviors. 6. **Report Files (from the Conversion Service)**: Generated reports can provide context on the tasks or processes that were running when an issue occurred. All the data collected is strictly used for support and diagnostic purposes. We ensure that every piece of information is treated with the highest standards of confidentiality and security. Transmitting this data allows our support team to understand the context better and pinpoint the root causes of issues, ensuring efficient resolution. We understand and respect the importance of your data's privacy and integrity. All data is securely transmitted, and we adhere to rigorous data protection standards to ensure the safety of your information. For any concerns or further questions about our data collection practices, please contact our support team or review our comprehensive privacy policy. --- ## Statistics Information about the past activity of the service is reported by the Statistics tab of the Conversion Service Configurator GUI, which is added to the Windows start menu during installation. With this tab, the conversion history of the service can be analyzed. The Statistics tab consists of the following parts: - [Filters](#filter-section): A section containing a set of filters to control the data displayed in the tab. - [Simple statistics](#simple-statistics): An overview displaying the performance of the service. - [Processed jobs](#processed-jobs): Pie chart about the results of the processed jobs. - [Activity](#activity): Time chart indicating service's load and performance for a selected group of jobs. In addition, the data displayed in the tab can be exported for further analysis. ## Filter section In the top row of the tab, below the title, the following filters can be configured to be applied to the data displayed in the tab: **Time unit & period** Determines the period of time when the jobs were processed. Use the time-unit selector to set the length of the period: - Day - Week - Month To pick the point in time where the period occurred, click the calendar icon and choose a date from the calendar, or step through periods using the arrow buttons. **Workflows** Filter data to show usage, load, and job results of specific workflows. **Query time** The time point when the query for the displayed data was made. The query time is only relevant if the current day is part of the selected time period. The query time can be updated with the refresh icon in this case. ## Export data as CSV Click **Export Data as CSV** in the top-right menu to export the data selected by the filters from the database. When the export has finished, a ZIP archive containing the following CSV files is saved: `service.csv` contains the following columns: - `started`: Service start time. - `stopped`: Service stop time. - `maxConcurrentTasks`: Concurrency supported by the license, i.e. the maximum number of tasks which can be executed in parallel. For more information, see [Health & Activity](https://www.pdf-tools.com/docs/conversion-service/monitor/health-activity). `jobs.csv` contains the following columns: - `id`: Row number. - `jobId`: Unique identifier name of the job. - `workflow`: Name of the workflow the job was processed with. - `profile`: Name of the profile the job was processed with. - `started`: Point in time when the service started to process the job. - `finished`: Point in time when the service completed the job. - `error`: Name of the error if the job failed. - `warnings`: List of the names of the warnings that occurred when processing the job. - `outputFilesCount`: Total number of output files resulting from the conversion. - `overallOutputSize`: Total number of bytes summed over all output files resulting from the conversion. - `overallPages`: Total count of pages summed over all output files resulting from the conversion. `tasks.csv` contains the following columns: - `id`: Row number. - `job`: Row number of the job the task is associated with tasks. - `queued`: Point in time when the task began waiting in the queue for being processed. - `started`: Point in time when the task moved out of the queue and the service started to process it. - `stopped`: Point in time when the service was finished with processing the task. - `component`: Names the type of processing step applied through this task. ## Simple statistics Displays some characteristic numbers about the jobs considered by the current filter configuration and the service: - **Service uptime**: The total amount of time that the service has been running. - **Processed jobs**: The total number of jobs that have been processed. - **Processed pages**: The total sum of pages of documents converted to PDF. - **Processing time**: The total sum of job processing time. Note that this number can be higher than *Service Uptime* since multiple tasks can be processed in parallel. - **Output file size**: The total sum of output file size of the processed documents. ## Processed jobs The pie chart summarizes the jobs considered by the current filter configuration in the following categories: - **Jobs successful**: Jobs converted successfully. - **Jobs with warnings**: Jobs converted with warnings. - **Jobs failed**: Jobs that failed with errors related to the input document like for example *Corrupt*, *UnsupportedFormat* or *Generic*. - **Jobs with errors**: Jobs that failed due to a *Timeout*, *Configuration* or *Internal* error. - **Jobs canceled**: Jobs that were canceled by the user. ## Activity The time chart indicates the service's load and performance. The filters apply to this diagram as well. It displays the following two curves: - **Utilization** (green): Plots the percentage of processing capability used. The total possible processing capability of the service depends on your license and your system. - **Number of tasks in queue** (yellow): Shows the number of tasks waiting in the queue to be processed. On top of the diagram, on the very right, there are four numbers, each next to a symbol. These values are in the color of the curve they are associated with. The top green value is the maximum. The bottom green value is the average of the utilization. The top yellow value is the maximum number of tasks in queue for the selected period. The bottom yellow value is the average time a task spends waiting in the queue before being processed. When you change the selected item in the legend at the bottom of the chart, the curve it represents is brought to the foreground together with its associated grid for easier reading. Note that for the Y-axis, the range of values is labeled on the right side. --- ## Conversion Service release notes Review what's new in the Conversion Service. These release notes provide the latest functional changes, additions, and selected bug fixes or performance improvements. **tip: To update to the latest version, see **[Update the Conversion Service](https://www.pdf-tools.com/docs/conversion-service/update/)**.** --- ## Version 6 The following sections provide updates in version 6 of the Conversion Service. ### 6.11.0 05 May 2026 #### Added - **Standard Converter for Office documents** With this release, the Conversion Service converts Word, Excel, and PowerPoint files to PDF without requiring a Microsoft Office installation, Microsoft 365 subscription, or Office license feature. The Standard Converter is enabled by default and works on both Windows and Docker deployments. For highest visual fidelity, configure a [local Microsoft Office installation](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#local-microsoft-office-installation) or the [Office for the web service](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion#office-for-the-web-service). - The Standard Converter supports the following profile options: - **Track Changes** (Word): Renders revision marks (insertions, deletions, formatting changes) in the converted PDF. - **Allow Scaling** (Excel): Scales worksheet columns to fit on one page. - Added a **Force line break** option to preserve Rich Text Format (RTF) line breaks in email text. Generic RTF control-word stripping prevents leftover control characters in the output. - Added an **Include external stylesheets** option, separate from **Include external images**, so you can skip external CSS independently. - Added missing features to Configurator Web, reducing the gap between the capabilities of the Windows-based Configurator and the Configurator Web. The following features are now available in the Configurator Web: - Signing, Stamping, Annotations and OCR configuration in profiles. - Connector configuration for all connector types, including the ability to create new connectors and edit existing ones. #### Fixed - Before this update, PPTX files with restricted embedded fonts caused conversion to hang. As a consequence, jobs stalled and didn't return a result. With this update, the service strips restricted embedded fonts before conversion. As a result, these PPTX files convert without hanging. ### 6.10.0 13 March 2026 #### Added - Convert documents into structured XML data using the **Convert to XML** workflow. For more details, review [Convert to XML workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/convert-to-xml) documentation. - With this release, Licensing Gateway Service supports forward proxy configuration. For more details, review [Configure a forward proxy](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/#configure-a-forward-proxy). #### Changed - Renamed workflows in the Conversion Service Configurator to better describe their purpose. The following workflows have been renamed: | Previous name | New name | |-----------------|----------------------| | Conversion | Convert to PDF | | Dossier | Create Dossier PDF | | Archive PDF/A-1 | Archive as PDF/A-1 | | Archive PDF/A-2 | Archive as PDF/A-2 | | Archive PDF/A-3 | Archive as PDF/A-3 | | Invoice | Prepare Invoice PDF | | Sign | Sign PDF | | Archive TIFF | Archive as TIFF | | Extraction | Extract XML from PDF | - Removed the **Accessibility** workflow from the Conversion Service. #### Fixed - Before this update, when converting Word documents containing field codes (such as `{ FILENAME }`), the field values displayed Conversion Service temporary folder paths instead of the original values. With this update, field codes retain their original values in the converted documents. ### 6.9.1 2 March 2026 #### Changed - During Word-to-PDF conversion, Word opens documents without updating external links (`UpdateLinksAtOpen = false`). Previously, documents with external image or data references combined with `<w:updateFields w:val="true"/>` triggered a security dialog that blocked COM automation, causing Word to stop responding and time out. The underlying issue was fixed, and as a result, documents with linked external content, such as images on network shares, use the cached version stored in the document rather than refreshing links during conversion. ### 6.9.0 24 February 2026 #### Added - Added support for converting S/MIME signed emails (`.p7m`). Before this change, signed emails failed to convert. As of this release, the Conversion Service unwraps the signature and converts the email content. Signature validity isn't verified. Encrypted signed emails aren't supported. - Added a progress indicator (spinner) in the Configurator during service start, stop, and restart operations. The spinner replaces the service control buttons while an operation runs, providing visual feedback and preventing accidental duplicate operations. #### Changed - Warning events in the Conversion Service Configurator now use subcategories within their top-level categories, such as Document Integrity, External Resources, Visual Fidelity, and Removed Features under the General category. Each warning also displays which input file types it applies to (PDF, HTML/email, Image, and Office). This makes it easier to find and understand relevant warnings when configuring workflow profiles. - Updated Conversion Service license agreement. #### Fixed - Fixed trailing `` tags and whitespace-only nodes in email HTML bodies causing extra blank pages in PDF output. - Fixed attachment names overlapping in email headers by preserving valid XML whitespace characters (tabs, newlines) when sanitizing HTML. ### 6.8.0 21 January 2026 #### Added - Added OpenTelemetry (OTLP) support for exporting traces, logs, and metrics to observability backends such as Grafana, Datadog, Seq, and Jaeger. For more information, review [OpenTelemetry (OTLP)](https://www.pdf-tools.com/docs/conversion-service/monitor/opentelemetry) documentation. - Added an offline activation wizard in the Conversion Service Configurator for managing license keys in full offline mode. For more details, review [Full offline mode activation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#full-offline-mode-license-activation) section. - Added license expiration date display in the Configurator. #### Changed - Custom XMP metadata handling preserves existing document metadata (Author, Title, Subject, Keywords) when setting individual XMP fields, such as `xmp:CreatorTool`. - License state validation now detects licenses that have been removed from the online Licensing Gateway Service (LGS). As a result, licenses that were previously hard to remove are now properly cleared from the Conversion Service Configurator. - Removed **License not added** pop-up on Configurator startup. - Removed .NET Framework 4.7 requirement from the installer. #### Fixed - Fixed Configurator memory leak caused by event handlers. - Fixed license validation incorrectly marking licenses as invalid when using a remote LGS. - Fixed Archive workflows failing with `ArgumentException` when resizing PDF forms containing AcroForm fields. ### 6.7.0 17 December 2025 #### Added - As of this release, you can extract XML data from documents processed by the Pdftools OCR Service using the **Extraction** workflow. This workflow uses the **Result Mode** option in the Configurator OCR Settings to output the structured XML from OCR results. - Added mail connectors in Docker deployments. - You can now import `Connections.xml` and configure mail secrets in Docker. - Mail connectors can now process email body and attachments separately. - Added license-based access control for the Conversion Service Configurator. Most of the tabs are now hidden when no valid license key is set and are displayed when you activate a valid license key. - Added quick file removal options in the Conversion Service Client user interface, including a right-click context menu with **Remove selected** and a trash icon when you hold the pointer over items in the input list for deletion. - Improved the **Processing Steps** user interface in workflows. Optional processing steps now display clickable links that jump to the relevant configuration section with checkmarks or warning icons indicating whether settings are complete. - Added a splash screen for the Conversion Service Configurator. #### Changed - Conversion Service [Docker image](https://hub.docker.com/r/pdftoolsag/conversion-service) size reduced by ~4% (1.87 GB to 1.8 GB). - Configuration Updater [Docker image](https://hub.docker.com/r/pdftoolsag/configuration-updater) size reduced by ~45% (238.75 MB to 131.75 MB). - * Office conversion is disabled by default. You can configure an Office user from the pre-processing step in workflow setup or in the Conversion Service tab. Once configured, a prompt asks whether to enable Office conversion for all workflow profiles or leave it disabled for manual configuration per profile. #### Fixed - Improved OCR error logging with more descriptive messages when OCR Service errors occur. - Updated vulnerable packages for improved security. - Optimized the Conversion Service Configurator graphical interface performance. ### 6.6.1 26 November 2025 #### Added - Added profile option **Keep Metadata** in optimization profile configuration that preserves custom metadata in output PDFs. Previously, certain optimization profiles could remove custom metadata during the conversion process. ### 6.6.0 28 October 2025 #### Added - As of this release, your page credits consumption under the **License** tab in the Conversion Service Configurator. - Added **Gmail connectors** for integration with Gmail accounts. The new connectors include: - **Watched Mailbox (Gmail)**: Input connectors that convert emails from Gmail mailboxes. - **Output Mailbox (Gmail)**: Output connectors that copy processed files to Gmail mailboxes. - **Send Email (Gmail)**: Email sending connectors that send notifications and results through Gmail SMTP server. Each Gmail connector type supports two authentication methods: - **App Passwords**: Authenticate using Gmail App Passwords, which requires 2-step verification. - **OAuth 2.0**: Authenticate using your organization’s OAuth credentials from Google Cloud Console. Provides organization-level control over email access, independent credential management, and dedicated rate limits that are separate from those of other users. All of these connectors include IMAP/SMTP settings optimized for Gmail. For more information, review [Gmail connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-gmail) documentation. - You can now extract property values generated through the workflow components and use them where available with the placeholder syntax. - The Dossier workflow now lets you configure PDF annotations that can be positioned on PDF dossier pages and table of contents pages. #### Fixed - Fixed an issue with widget annotation text not present in the output after PDF/A conversion. - The MSG files attached to emails have properly rendered characters. - The license agreement has been updated to the new terms and conditions. ### 6.5.0 17 September 2025 #### Added - Added a new **Output File Settings** section in the [Dossier](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier) workflow configuration, introducing configurable attributes for invalid filename characters and maximum filename length. - As of this release, you can now convert JPEG File Interchange Format (JFIF) images to PDF. The JFIF conversion to PDF is included in the following workflow profiles: - [Conversion](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion) - [Archive PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) - [Archive PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3) - [Archive PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1) - [Archive TIFF](https://www.pdf-tools.com/docs/conversion-service/workflows/tiff) - As of this release, you can linearize PDF documents during the conversion process. This will create a PDF document that is optimized for fast web viewing. Linearization is available in the following workflow profiles: - [Conversion](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion) - [Archive PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) - [Archive PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3) - [Archive PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1) #### Fixed - Fixed an issue with a multi-level table of contents creation in the Dossier workflow that failed under certain conditions. For more information, review [Dossier](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier) documentation. ### 6.4.2 4 September 2025 #### Fixed - The License Gateway Service (LGS) mode in the Conversion Service Configurator is now automatically refreshed. There are two available modes, [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) and [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/). - Fixed an issue where `.msg` files containing non-Latin characters could render incorrectly during conversion. This release resolves the issue by improving the font matching logic to resolve font table selection correctly. ### 6.4.1 7 August 2025 #### Fixed - Fixed stack corruption when creating an annotation appearance. This issue led the workers to a crash and fail conversion with an `EndOfStreamException` error. ### 6.4.0 30 July 2025 #### Added - As of this release, you can use the Pdftools OCR Service with the Conversion Service. This OCR configuration is compatible with the legacy 3-Heights® OCR Service and doesn't require any additional configuration for users who have already integrated the legacy OCR. Review [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) documentation for setup and configuration details. - You can now choose to hide the default header that is added when converting emails to PDF. #### Changed - The **Header time format** subsection was renamed to **Header** in the **Email Settings** configuration section. - In the workflow and profile configuration, the **3-Heights® OCR Service** engine was renamed to **Pdftools OCR Service (3H Legacy Compatible)**. ### 6.3.0 24 June 2025 #### Added - You can now add annotations to PDF documents. Annotation can be moved, resized, or removed in a viewer where a user can edit the PDF. Review [Stamp and annotation](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping) documentation for configuration details and more information. - With this update, you can set up a fallback time-stamp authority (TSA) in the Conversion Service Configurator. As a result, you can add a backup TSA URL that the Conversion Service will use if the primary TSA isn't available. #### Changed - The following changes were made in the Conversion Service Configurator. - The **Document Optimization** processing step (included in all PDF/A workflows) was renamed to **Compression and Optimization**. - The **Stamping** processing step was renamed to **Stamp and Annotation**. - The **Warnings** configuration section was renamed to **Events**. Previously, this configuration section name was the same as one of its main contents (which are warning, error, ignore). The **Events** configuration section lets you configure which issues detected during the workflow processing are only logged as a warning, ignored, or stop the processing with an error. #### Fixed - Fixed an issue where the **Event Date** in MSG files was not serialized correctly. - Resolved an error that occurred when converting EML files in **Collect Mode** was set to **Separate for Job** in the **Conversion** workflow. ### 6.2.0 23 May 2025 #### Added - As of this update, you can use the Licensing Gateway Service (LGS) in the full offline mode with the Conversion Service. For more information, review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) documentation. - With this update, you can now use a new accessibility workflow designed to validate PDF compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**. Note: The Accessibility workflow was removed in [version 6.10.0](#6100). - You can now import and export profiles in the Configurator Web (beta). Making it easier to share and manage profiles across different instances of the Conversion Service. For more details, review [Configure profiles using Configurator Web](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker#configure-profiles-using-configurator-web) section. #### Changed - We have removed the `latest` tag from the Conversion Service Docker images to align with Docker best practices and improve version traceability. As a result, when using the `docker run` command, Docker Compose YAML files, or any other Docker configuration files, the `image: pdftoolsag/conversion-service:` can no longer set to the `latest`, but only to specific versions, such as `6.2.0`, `6.2`, `6`. Please make sure you reference specific version tags when pulling Docker images. ### 6.1.0 14 April 2025 #### Added - As of this release, the Conversion Service offers more predefined input connectors for new users upon installation. These connectors leverage the Simple API and highlight the most commonly used workflow profiles. When the Conversion Service is running locally or on an IP address that you specify in the `baseURL`, you can test these connectors using the [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json) or the [Simple API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api). The Conversion Service Configurator doesn't display the updated connectors for users who already have the Conversion Service installed. To access the new connectors, uninstall the Conversion Service, delete the associated configuration files from the installation folder, and then reinstall the Conversion Service. This process was implemented to avoid confusion for users who have already configured their connectors. Although the Postman collection has been updated, you can still access the previous default Simple API endpoints from the legacy folder. Additionally, the previous default PDF/A-2 REST input (plain HTTP) and PDF/A-2 input JSON connectors remain compatible and are located in the **Archive PDF/A-2** folder in the Postman collection. - You can now configure Microsoft Office file conversion in the Configurator Web (beta), alternative to the Conversion Service Configurator that lets Docker users change the Conversion Service configuration without the need of exporting files from a Windows Server machine. The Configurator Web is still in beta and does not yet support all the capabilities of the Windows-based Conversion Service Configurator. For more details, see the [Configure profiles using Configurator Web](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker#configure-profiles-using-configurator-web) section. #### Changed - Previously, the LGS only gathered data about the number of pages processed by the Conversion Service. As of this release, LGS also collects and reports the number of pages processed using a specific Conversion Service workflow. As a result, both the number of pages processed (volume) and the workflow which was used by the Conversion Service is reported through the LGS. #### Fixed - Improved configuration validation for Send Email (SMTP) and Send Email (Exchange Online) output connectors. With this release, the Conversion Service Configurator prevents invalid configurations where a job status is set to **Error** and **Attachments** is set to **Result Files**. This validation prevents potential issues since error jobs don't produce any result files to attach. - Prior to this release, the **Allow Resize PDF** feature did not correctly handle landscape-oriented documents, causing unexpected rotation to portrait format and loss of redactions after conversion, leading to formatting issues. As of this release, a new resize-tolerance property was introduced to provide configurable control over resizing behavior. As a result, landscape orientation and redactions are preserved, and resizing can be fine-tuned based on specific requirements. - Previously, a refactoring of the Docker image caused profile import to fail in the Conversion Service container, resulting in a startup error when accessing `Workflows.xml`. This release fixes the issue by adjusting the Docker image, and profile import now works as expected during container startup. ### 6.0.0 3 March 2025 #### Added - As of this update, you can set up Conversion Service profiles and workflows in Docker, enhancing the experience for Docker users. You no longer need to install the Configurator on a Windows Server machine to export configuration files to your Docker instances. The first version of the Configurator Web is still in beta and does not yet support all the capabilities of the Windows-based Conversion Service Configurator. For more details, see the [Configure profiles using Configurator Web](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker#configure-profiles-using-configurator-web) section. - You can now learn how to integrate the Conversion Service using OpenShift with a [Conversion Service on OpenShift](https://www.pdf-tools.com/docs/conversion-service/configure/configure-openshift) guide. - With this update, you can use the same license key with unlimited number of LGS instances used with the Conversion Service. #### Changed - As of this version, you no longer need to use the `msiexec /i ConversionService-VERSION_NUMBER.msi PDF_TOOLS_DISABLE_OS_CHECK=1` command to enable installation of the Conversion Service on regular Windows machines. This makes the installation process simpler and more straightforward for evaluating users and for users who need to export the configuration files from regular Windows machines. #### Fixed - Configuration stability improvements when removing Microsoft Office users. ## Version 5 The following sections provide updates in version 5 of the Conversion Service. ### 5.7.6 24 July 2025 #### Fixed - As of this release, lifecycle management has been added for the native error callback to prevent `EndOfStreamException` errors caused by callbacks referencing garbage-collected delegates. ### 5.7.5 28 April 2025 #### Fixed - Prior to this release, the **Allow Resize PDF** feature did not correctly handle landscape-oriented documents, causing unexpected rotation to portrait format and loss of redactions after conversion, leading to formatting issues. ### 5.7.0 23 December 2024 #### Added - As of this update, you can convert WebP images to PDFs. - You can now export word track changes (redlining) to PDF. For more details, review [Configure conversion of redlined Microsoft Word documents](https://www.pdf-tools.com/docs/conversion-service/configure/word-track-changes). - Previously, you could only skip creating the table of contents in the Dossier workflow. As of this update, the Conversion Service Configurator lets you also skip the creation of outlines (bookmarks) in the Dossier workflow. To skip the outline creation, go to the Dossier workflow configuration and disable the **Outline (Bookmarks)** toggle. When the previously described **Outline (Bookmarks)** option is enabled, the **Outline (Bookmarks)** configuration section includes the **Document Bookmark** toggle. If you disable this toggle, bookmarks from various files that are merged into a dossier are no longer nested as children but are all included at the same level. #### Changed - With this update, the **Troubleshooting** tab of the Conversion Service Configurator displays issues detected in profile and connector configuration validation. - Previously, you could accidentally install the Conversion Service Client on a machine where the Conversion Service was already installed, causing the service to malfunction. As of this release, you can no longer install the Conversion Service Client when the Conversion Service is already installed on the same machine. ### 5.6.0 8 October 2024 #### Added - You can now configure the default address of the Connector Service. For more details, review [Connector service host address](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service#https) section. #### Changed - Previously, the Conversion Service Configurator included separate toggles for **Add Outlines** and **Hide Outlines**. This feature is available in the Archive PDF/A-1, Archive PDF/A-2, and Archive PDF/A-3 workflows. With this update, the previously separate toggles are now moved into one dropdown menu with the following three options: **Display**, **Hide**, and **Remove** #### Fixed - As of this release, the conversion of HTML, XML, MSG, and EML files is improved. ### 5.5.0 29 August 2024 #### Added - A new welcome window is displayed when you open the Conversion Service Configurator. The welcome window links to the [Getting Started](https://www.pdf-tools.com/docs/conversion-service/getting-started/) documentation, and you can disable it for the next sessions. - With this release, you can set which files attached to emails are skipped during conversion. For more information, review the following sections of the Email connectors documentation: - Watched Mailbox (IMAP) [Settings](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#settings) - Watched Mailbox (Exchange Online) [Settings](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#settings-1) #### Changed - With this release, the Pdftools no longer supports Microsoft Office 2016 and Windows Server 2016 with the Conversion Service. You can still utilize the Conversion Service on Windows Server 2016 and use Microsoft Office 2016 for file conversion. However, Pdftools doesn't provide technical support for new customers who use the mentioned versions. ### 5.4.0 24 July 2024 #### Added - Support **HTTPS** communication for [REST input JSON](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-json) and [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http) connectors. For details how to activate the **HTTPS** communication, review [HTTPS](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service#https) documentation. - You can now convert HTML files containing multimedia elements that are being removed during file conversion. Previously, attempting to convert HTML files with elements such as iframes, audio, or video resulted in an error. With this update, you can set **HTML Multimedia Removed** in the **Warnings** section of the profile configuration in the Conversion Service Configurator. As a result, you can skip multimedia elements from HTML files using the described configuration. - Set the **Allow Scaling** option for **Text Stamps** to ensure that the Conversion Service is not adding the stamp outside of the page boundaries. For more information, review [Configure stamping](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping) documentation. - With this release, you can specify which files the Watched Folder connector skips using glob patterns. For more information, review [Configuration options](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/folder-connectors#configuration-options) in the Watched Folder connector docs. - The Conversion Service adds outlines (bookmarks) to converted PDF files by default. Previously, there was no option to disable or hide the bookmarks. As of this update, options to remove or hide bookmarks are available for the following workflows: Archive PDF/A-1, Archive PDF/A-2, Archive PDF/A-3. - To remove the bookmarks: Disable the **Add Outlines** toggle in **Conversion Settings** > **Viewer Preferences** configuration section. - To hide the bookmarks: Enable the **Hide Outlines** toggle in **Conversion Settings** > **Viewer Preferences** configuration section. As a result, the bookmarks are still accessible in your PDF viewer but are hidden by default. - As of this release, you can now convert hidden attachments in emails (attachments that start with a dot). To use this feature, enable the **Include Hidden Attachments** toggle in **Email Settings** of the Configurator. - You can now remove format protection in the Office for Web configuration. Enable the **Remove Excel Format Protection** toggle in **Office Conversion** > **Office For Web Settings** configuration section. #### Fixed - Under certain circumstances, conversion of .MSG file to any PDF or PDF/A format resulted in images being replaced by placeholders in the output PDF files. This issue is now fixed and all images are displayed correctly. - Before this update, while using the Dossier Workflow, merging PDF with form fields of the same name as the PDF file overwrote the form fields. This issue is now fixed and all PDFs are displayed properly. ### 5.3.0 19 June 2024 #### Added - Proxy settings are now extended. Email-related connectors can now use a defined proxy URL if you enable it in the Configurator. Review [Proxy](https://www.pdf-tools.com/docs/conversion-service/configure/configure-win-service#proxy) configuration documentation for more information. - With this release, the Configurator introduces a **Troubleshooting** tab that offers solutions to detected issues. In this version, the troubleshooting functionality checks if the recommended Microsoft Defender rules are set. This feature will be expanded to include additional checks. - Profile option **Allow Resize PDF** in **Document Settings** configuration section. This option resizes the page using the value set in the **Default Page Size** option configured in the **Document Settings** section. If you disable this option, the original page size of the document is used. - Before this update, you could only convert email subject fields to titles during email to PDF/A conversion. With this update, you can now set the **Use Subject As Subject** configuration option in the **Email Settings** section of the Configurator that converts the subject of an email as a title and as a subject of the PDF file. #### Fixed - Previously, when configuring the **Child Removed** to **error** in the **Warnings** section of the profile settings, the Conversion Service prompted you with a warning instead of an error when removing the child files (files attached to emails or other document formats). With this update, the issue is fixed, and the configuration results in an appropriate error prompt when the Conversion Service removes child files in the described configuration. ### 5.2.0 9 May 2024 #### Added - Workflow **Archive TIFF**. For more information, see [Archive TIFF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/tiff) documentation. - Workflow **Sign**. For more information, see [Sign workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/sign) documentation. - New functionality to activate, update, and deactivate core-based license keys offline using the License tab within the Configurator. For more information, see [Legacy core-based license key](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#legacy-core-based-license-key). ### 5.1.0 3 April 2024 #### Added - Profile option **Include external images** in **Document Settings** configuration section. For more information, review [Configure output file appearance](https://www.pdf-tools.com/docs/conversion-service/configure/configure-emails#configure-output-file-appearance) section in the Configure email processing documentation. - An error code `external` in the REST interface for issues that can occur while trying to use an external service or load an external resource. - Conversion Service now supports Docker Compose. The Docker Compose lets you use the REST connectors, Watched Folder connector, and seamlessly update to a new version. For more information, see [Set up the service in Docker](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container). ### 5.0.0 29 February 2024 #### Added - The Archive PDF/A-3 workflow now has a new profile option **Flatten annotations** in section **Document Optimization**. - In the Configurator, you can now enable the Licensing Gateway Service on another machine by changing the license gateway address. For more details, see [Conversion Service licensing](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/) documentation. #### Changed - Dependency on Microsoft .NET Desktop Runtime 8.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 8.0 (Windows, x64). ## Version 4 The following sections provide updates in version 4 of the Conversion Service. ### 4.8.0 4 December 2023 #### Changed - Disabled office conversion for the integrated default workflow profiles in Docker. - Support workflow options for the REST input plain HTTP connector using placeholder syntax. Note: An update to version 4.8 may break the file processing due to breaking changes. Previously, all the query parameters were set as variables. With this update, you have to define the variables in the Configurator. For more information, see [REST input plain HTTP](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/rest-connectors/rest-input-connectors#rest-input-plain-http) in the REST connectors documentation page. ### 4.7.0 25 September 2023 #### Added - Support for consumption-based licensing. - As of this update, the Licensing Gateway Service is installed by default with the Conversion Service. - Configuration setting to set up custom job options. - The Configurator now includes a new tab **Licensing** for license management that can replace the separate license manager in most cases in the Conversion Service Configurator. #### Fixed - Improved support request. Added additional data for better insight in the Configurator. ### 4.6.0 26 July 2023 #### Added - Customization of email header date time formatting. ### 4.5.0 28 June 2023 #### Fixed - Improved conversion of email body and HTML documents. - Improved compatibility of mailbox connectors with Microsoft Exchange. ### 4.4.0 31 May 2023 #### Added - Enable export of analytics and redesign of Support tab. ### 4.3.0 3 May 2023 #### Added - As of this update, you can use new stamping functionality that allows page selection - All, First, and Last. - The **Collect Mode** setting **Separate** to convert a job with multiple files into separate output documents instead of a single output. - Configuration setting to preserve the body of the corresponding input email when used with result files. - Swisscom on-demand signature. - Allow job options for certain signature properties. #### Changed - Changed digital signature types to have a simpler overview. - Swisscom signature types were renamed to remove **All-in** from the signature type name. #### Fixed - Improved conversion of emails with non-standard structure. - Improved reliability and robustness of Office conversion. - Fix configuration updater to reflect new Swisscom signature type names. [patch v4.3.2] ### 4.2.0 30 March 2023 #### Added - Support for CSV files with whitespace around quoted fields without warning or error. - Detailed information for the Health & Activity, Services, and Statistics tabs are displayed in the documentation panel. #### Changed - Behavior for CSV files containing malformed data: CSV file containing malformed data now results in a configurable warning of type `CorruptionRepaired` instead of a hard error. #### Fixed - Improved UI design of the documentation panel. ### 4.1.0 17 February 2023 #### Added - With this update, Conversion Service supports download of external stylesheets in HTML, and XML file formats through a proxy. - Configuration option to specify the form field name of the files in the `multipart/form-data` content. ### 4.0.0 22 December 2022 #### Added - Settings for email, HTML, CSV, and XML conversion to control resizing and optimal fitting of content in case of content overflow. - Settings for Excel conversion to control resizing and optimal fitting of content in case of content overflow. #### Changed - As of this update, the default installation directory on Windows is `C:\Program Files\Pdftools\Conversion Service`. - With this update, the default program data directory on Windows is changed to `C:\ProgramData\Pdftools\Conversion Service`. ## Version 3 The following sections provide updates in version 3 of the Conversion Service. ### 3.11.0 15 December 2022 #### Added - Both Archive PDF/A-2 workflow and PDF/A-3 workflow lets you use a stamping functionality to add an image or 1D/2D barcode to the converted documents. - Dossier workflow Stamping functionality to add an image or 1D/2D barcode to the converted documents. ### 3.10.0 12 October 2022 #### Added - Option to convert Word, Excel, PowerPoint documents through the Azure cloud with the Microsoft Office for the web service. - Watched Folder connector received now supports companion files to pass information as variables directly to the output connectors. - Rest output connector received the following additions: - Support for sending form fields in addition to the files. - Support for username/password based authentication. - Support for setting the Accept header. ### 3.9.0 17 August 2022 #### Added - REST interface property `Status` in result of method `getJobResult` to get Success or Warning or Error status of job result instead of using legacy `Success` property. ### 3.8.0 27 June 2022 #### Fixed - Improved robustness in low memory conditions on Windows. ### 3.7.0 2 June 2022 #### Added - New dependency on Microsoft .NET Desktop Runtime 6.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 6.0 (Windows, x64). #### Fixed - Improved performance especially for small files. ### 3.6.0 3 May 2022 #### Added - Output connector **Send Email (SMTP)** to send an email to a configurable or dynamic email address, containing the results or original files or additional information (error message, warnings). - Output connector **Send Email (Exchange Online)** to send an email to a configurable or dynamic email address, containing the results or original files or additional information (error message, warnings). - Output connector **Create Text File** to create a text file with additional information (error message, warnings) in an output folder. ### 3.5.0 4 April 2022 #### Added - Profile settings and options in all workflows to add metadata to the documents. - Input connector **Watched Mailbox (Exchange Online)** to automatically convert emails or files sent to a configurable mailbox on a Microsoft Exchange Online server. - Output connector **Output Mailbox (Exchange Online)** to copy output files to a mailbox without actually sending an email. ### 3.4.0 23 February 2022 #### Added - REST interface now includes query parameter `url` on `addData` POST request to load a file directly from a webserver. - The REST interface method `storeJobResultData` to send the result file directly to a webserver via HTTP PUT/POST request. - Stamping functionality to add single-line text content to the converted documents. - Dossier workflow supports custom placeholder variables in Text Stamps. - Added conversion of signed Emails (s/mime). - You can now convert the OpenDocument Text (`.odt`), Spreadsheet (`.ods`), and Presentation (`.odp`) files through Microsoft Word, Excel, and PowerPoint, respectively. - With this update, you can use the output connector **Output Mailbox (IMAP)** to copy output files to a mailbox without actually sending an email. - Office add-ins for Word, Outlook, Excel and PowerPoint. ### 3.3.0 1 February 2022 #### Added - Support for Windows Server 2022. - Support for Office 2021 (64 Bit). - With this update, you can use **Archive PDF/A-1** workflow. - New conversion of WordprocessingML 2003 (`.xml`) and SpreadsheetML 2003 (`.xml`) documents through Microsoft Word and Microsoft Excel, respectively. #### Changed - Newly created bookmarks are now closed instead of open by default. - The Configurator now changed the export and import of profiles to also include the workflow activation state. ### 3.2.0 28 December 2021 #### Added - With this update, you can use an input connector **Watched Mailbox (IMAP)** to automatically convert email messages or files sent to a configurable mailbox on an IMAP server. - **Archive PDF/A-2 workflow**: - Use convert mode configuration for child documents (attachments) for detailed configuration of documents to convert. - Convert HTML, CSV and XML attachments. This functionality is disabled by default. - Configure a collect mode. This mode offers a detailed configuration of how to convert documents that have attachments, specifically how to combine the converted documents and how to handle errors when processing child documents. This supersedes the configuration options **Document Collection Mode** and **Child Error Handling**. - **Archive PDF/A-3 workflow**: - In the convert mode settings, you can now enable **Skip** and **Skip with Warning**, which lets you choose whether an informational event or a warning is generated when skipping (removing) a child document. The new default is **Skip with Warning**. When updating an installation, the profiles' behavior is not changed. - The **Dossier** workflow received the following additions: - Profile setting to control the horizontal alignment (Left, Center, Right) of the title of the table of contents. - Job option `TOC-OUTLINE-TITLE` to set the title of the bookmark for the table of contents. - Profile setting for automatic numbering of the entries in the table of contents. - Profile setting to apply stamps to the pages of the table of contents. - Optional preprocessing step to convert input documents to PDF. #### Changed - In the Dossier workflow, the document outline has been changed to contain a bookmark for the table of contents. ### 3.1.0 26 November 2021 #### Added - You can now activate or deactivate workflows in the [Workflows & Profiles](https://www.pdf-tools.com/docs/conversion-service/workflows/) tab. - Conversion of CSV, HTML (prepared for archiving) and XML documents. - The REST Output connector now supports placeholder variables in URL setting. - REST input JSON connector received the following additions: - Key `options` in JSON format to pass job-level and document-level options to the workflow. - Key `variables` in JSON format to pass information directly to the output connectors. #### Changed - In the Configurator, the **Profiles** tab was changed to **Workflows & Profiles**. - The REST input JSON connector changed the default request body size limit from unlimited to 100 MB. #### Fixed - Improved UI design to provide a clear overview of the job progress and results. ## Version 2 The following sections provide updates in version 2 of the Conversion Service. ### 2.12.0 15 October 2021 #### Fixed - The Configurator now provides greater clarity of errors and warnings, an improvided UI validation of service, profiles, and connection configuration. ### 2.11.0 21 September 2021 #### Added - Combine multiple PDF files into one dossier with the **[Dossier](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier)** workflow. The dossier applies headers, footers or watermarks [v2.8] and supports title page and customizable table of contents. - **PDF to PDF/A conversion:** - New warning types *Annotation removed* and *Multimedia removed* for events that were previously reported as *Action removed*. - New conversion of HEIC and HEIF images. - Configurator now includes **[Statistics](https://www.pdf-tools.com/docs/conversion-service/monitor/statistics)** tab to report and analyze the service's conversion history. - New possibility to copy profiles and connections. #### Fixed - Improved conversion event messages to be more specific. - **PDF to PDF/A conversion:** - Improved detection of optimal target conformance level where the highest level is chosen that can be achieved with a perfect conversion. ### 2.10.0 4 August 2021 #### Added - Client installer (msi). - Tab **[Health & Activity](https://www.pdf-tools.com/docs/conversion-service/monitor/health-activity)** for monitoring the state and recent activity of the service. - REST input connector for structured JSON requests. #### Changed - Changed trademark ™ to registered trademark ®. #### Fixed - Improved processing of signed PDF documents: If signatures need to be removed, their visual appearance is preserved. ### 2.9.0 4 August 2021 #### Added - Support for HTTPS service endpoint. - Dependency on Microsoft .NET Desktop Runtime 5.0 (Windows, x64) and Microsoft ASP.NET Core Runtime 5.0 (Windows, x64). - REST input connector for plain HTTP requests. - REST output connector. - Command Excecute output connector. ### 2.8.0 16 June 2021 #### Added - Workflow **[Conversion](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion)** provides document conversions from multiple file formats to PDF with an emphasis on performance and document size. - In the Archive PDF/A-2 workflow, you now can use a profile option for emails *Use subject as filename*. ### 2.7.0 12 May 2021 #### Added - In the Archive PDF/A-2 workflow, you now can use a profile option for emails *Use subject as filename*. - Profile option *Child error handling*. #### Fixed - Improved email conversion: Attachments of emails where parts of the attachment are removed during the conversion process (e.g. a not convertible part of a ZIP file) are now listed as *Partially removed* inside the email header. - Improved UI design of the profiles tab to provide a clear overview of profiles and their related workflow. ### 2.6.0 15 April 2021 #### Added - New `Configuration` and `Timeout` job result error codes in the REST interface. - New support for load-balancing to multiple instances of 3-Heights® OCR Service. #### Fixed - Improved conversion of DOCX documents: Certain corrupt documents are now repaired automatically. - Improved conversion of password-protected DOCX documents: Embedded files from these documents can now be processed. ### 2.5.0 16 March 2021 #### Added - Workflow **[Archive PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3)** similar to **[Archive PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2)**, but with support for non-PDF/A attachments. - Workflow **[Invoice](https://www.pdf-tools.com/docs/conversion-service/workflows/invoice)** for creating PDF/A-3 conformant invoices with attachments. - Signature types *Windows - PAdES-B-B* and *PKCS#11 - PAdES-B-B* to create basic signatures that require no TSA nor revocation information. ### 2.4.0 17 February 2021 #### Added - Tab **[Integration](https://www.pdf-tools.com/docs/conversion-service/integrate/)** for configuring connections to allow easy integration of the Conversion Service into existing systems. - New service **Conversion Service Connections** that allows combining input sources with output for easy integration into existing systems. #### Changed - Removed service **Conversion Service Folders** (superseded by the new service **Conversion Service Connections**). - The value of property `type` of problem details object (RFC 7807) was changed to `http://www.pdf-tools.com/service/rest/errors/‹type›`. #### Fixed - Improved OCR recognition task scheduling: Each page is now processed in a separate task, which significantly reduces the amount of time a worker is blocked by OCR tasks and thus improves the latency of other high priority tasks. - Improved OCR engine configuration: Specific configuration for each engine type. ### 2.3.0 29 January 2021 #### Added - The REST interface now supports Cross-Origin Requests (CORS). By default, requests from all origins are allowed. - **Archive PDF/A-2 workflow**: Profile option *Flatten annotations* in section **Document Optimization**. ### 2.2.0 16 December 2020 #### Added - Docker image `pdftoolsag/conversion-service`. - Changed license key format to `4H-VX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX`. License keys with the format `1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX` are no longer supported. - Conversion of RTF documents. ### 2.1.0 #### Changed - A parallel installation of the 3-Heights® Document Converter is no longer required and no longer supported for this purpose. ### 2.0.0 #### Added - Profile setting *Task timeout* for all workflows, to avoid the situation where a single long-running processing step can lead to timeouts in other unrelated jobs. #### Fixed - Improved email conversion: Attachments of emails where parts of the attachment are removed during the conversion process (e.g. a not convertible part of a ZIP file) are now listed as *Partially removed* inside the email header. - Improved and harmonized messages of warnings and events. - Improved conversion of Word, Excel, and PowerPoint: These types of documents are now converted directly within the Conversion Service through Microsoft Office applications. ## Version 1 This section describes all changes included in version 1 of the Conversion Service. #### Added - New requirement of Microsoft Windows Desktop Runtime 3.1 (Windows, x64) and Microsoft ASP.NET Core Runtime 3.1 (Windows, x64). This is in addition to the .NET Framework 4.7. - View in the 4-Heights® Conversion Service Configurator GUI for submitting a support request. - Profile option for job priority in Archive PDF/A-2 workflow. - Profile configuration (Digital Signature) available in the Configurator GUI. - Attachment information is shown as part of the email header. - Possibility to import/export profile configurations. - License-dependent view in the Conversion Service Configurator GUI for installing plugins. - Document content overflow into the margin when converting emails is signaled with `ContentOverflowWarning`. - Documentation panel in the Conversion Service Configurator GUI. - Codes in the service status response of the REST interface. - Service setting for proxy configuration. - GUI Client for manual processing. #### Changed - Changed minimum required version of 3-Heights® Document Converter Enterprise Edition to version 6.5. - Changed port to connect to 3-Heights® Document Converter Enterprise Edition to 7983. - **REST interface**: - Changed to return RFC 7807 Problem object instead of proprietary error object. - Changed JSON serialization of `enum` values from integer to string. - Changed XML objects to use no namespace in accordance `withopenapi.yaml`. --- ## Update Conversion Service Learn how to update the Conversion Service to the latest version in Windows Server or Docker. --- ## Update Conversion Service in Docker Learn how to update the Conversion Service to the latest version in Docker. ## Automatic update If you use the Conversion Service with Docker Compose, you can configure an automatic update. To update the Conversion Service in Docker: 1. Change the value of the `IMAGE_VERSION` variable in the `.env` file to the latest version. 1. Add the Configuration Updater to your `docker-compose.yaml` file: ```yaml configuration-updater: # Configuration Updater - Updates configuration files for both connector-service and conversion-service. image: pdftoolsag/configuration-updater:$IMAGE_VERSION volumes: # Utilizes vol-conversion-srv for updating Conversion Service configurations. - vol-conversion-srv:/app/conversion-config # Utilizes vol-connector-srv for updating Connector Service configurations. - vol-connector-srv:/app/connector-config ``` Replace the `IMAGE_VERSION` with the Conversion Service version number. For example: `6.0.0`, `6.0`, `6` 1. Optional: If you are updating the Conversion Service to the new major version, you need to change the license key also. For example, change the version 4 license key: ``` 4H-V4-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX ``` To the version 6 license key: ``` 4H-V6-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX ``` The major version of the Conversion Service for which a specific license key is valid is included in the license key itself. In the previous two examples, you can see the `V4` and `V6`. 1. Run Docker Compose: ```bash docker compose up -d ``` For more information, see [Docker Compose configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container#docker-compose-configuration). :::note[Before you begin] All relevant files, such as `appsettings.json` and workflows, are backed up during the update. Restore your installation using these files in the unlikely event of an error during the update process. **caution: When you update the Conversion Service installation to the latest version, the configuration is **no longer compatible with previous versions**.** ## Manual update If you are using a standalone Docker container, you can update the Conversion Service manually: 1. Update the Conversion Service using the Windows Server approach. Review [Update Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/update/windows-server). 2. [Import updated profiles](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker) to new containers based on the new version of the `pdftoolsag/conversion-service` image. --- ## Update Conversion Service on Windows Server Learn how to update the Conversion Service to the latest version on Windows Server. ## Procedure :::note[Before you begin] In the Conversion Service Configurator, review the current version of the Conversion Service. Go to the **About** tab, where you can view the version number and the installation directory. All relevant files, such as `appsettings.json` and workflows, are backed up during the update. In the unlikely event of an error during the update process, you can restore your installation using these files. To update to the latest version of the Conversion Service, follow these steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. In the **Product builds** section, find the `conversion-service-VERSION_NUMBER.msi` package, and then click **Download**. Check the name carefully to identify the latest version, as you may have access to more than one version. 1. Open the MSI installation package to run the installer. 1. In the installation wizard, click **Next**. 1. Read the license agreement, select the **I accept the Terms** checkbox, and click **Next**. 1. Click **Install**. 1. Once the process has been completed, click **Finish**. **caution: **Ensure that the Conversion Service remains installed** during updates. Uninstalling it will result in the loss of your Microsoft Office configuration. If this occurs, reconfigure your [Office setup](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion).** ## Additional information Use the installer to update the complete Conversion Service installation, including workflows, profile configurations, and integrations. It updates the service and the main client (GUI client and shell client). The installer detects the current installation version and updates all required files as appropriate. ### Available installers To update either the Conversion Service or its clients, use an appropriate installer: 1. **Windows Server**: The `conversion-service-VERSION_NUMBER.msi` installs the Conversion Service itself and provides interfaces that let you configure workflow profiles and more. This installer comes with the following interfaces: - Conversion Service Configurator - PDF Client for Conversion Service - Conversion Service shell client (CLI) - Licensing Gateway Service 1. **Windows** clients: `conversion-service-client-VERSION_NUMBER.msi` to install the following interfaces: - PDF Client for Conversion Service - Conversion Service shell client (CLI) - Office Add-ins You can use the installer to update from any version to the latest version. If the installer does not detect any existing Conversion Service configuration, it installs a new instance of the Conversion Service. ### Restore previous configuration **caution: When you update the Conversion Service installation to the latest version but later decide to downgrade back to the previous version, the configuration files are **incompatible with the previous version**.** If you need to downgrade the Conversion Service to the previous version, restore your previous configuration using automatically created backups with the following steps: 1. Uninstall the Conversion Service, and then install the previous version. 1. Locate the following backup configuration files in the installation folder: - `Workflows (Backup DATE_AND_TIME).xml` - `appsettings (Backup DATE_AND_TIME).json` - `Connections (Backup DATE_AND_TIME).xml` Example paths: ```powershell C:\Program Files\Pdftools\Conversion Service\bin\Workflows (Backup 2024-12-02 02-38-11).xml C:\Program Files\Pdftools\Conversion Service\bin\appsettings (Backup 2024-12-02 02-38-11).json C:\Program Files\Pdftools\Conversion Service\bin\Connections (Backup 2024-12-02 02-38-11).json ``` 1. Rename each file by removing ` (Backup DATE_AND_TIME)` then replace the default configuration files with these backups. --- ## Workflows A workflow represents a broad use case and defines the general conversion process. Workflows are tailored to a specific use case, which is also reflected in the available configuration settings. All workflows provided cannot be changed. The Conversion Service provides the following workflows: - [Archive as PDF/A-1](#archive-as-pdfa-workflows) - [Archive as PDF/A-2](#archive-as-pdfa-workflows) - [Archive as PDF/A-3](#archive-as-pdfa-workflows) - [Archive as TIFF](#archive-as-tiff) - [Convert to PDF](#convert-to-pdf) - [Convert to XML](#convert-to-xml) - [Create Dossier PDF](#create-dossier-pdf) - [Extract XML from PDF](#extract-xml-from-pdf) - [Prepare Invoice PDF](#prepare-invoice-pdf) - [Sign PDF](#sign-pdf) You can select **specific configuration settings** for the workflow via **[profiles](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles)**. You can **add [stamps](https://www.pdf-tools.com/docs/conversion-service/workflows/stamping)** during the conversion process, and **configure the [metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** in the resulting output PDF. ## Archive as PDF/A workflows These workflows are engineered specifically for preparing documents for archiving. They assure conformance according to three specifications: - **[Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2)**: Default workflow for archiving. - **[Archive as PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3)**: Features and steps are identical to PDF/A-2, but allows you to embed attachments that are not in conformance with PDF/A. - **[Archive as PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1)**: Older version of the PDF/A standard. It is used where PDF/A-2 or PDF/A-3 conformance is not possible. **info: The Conversion Service automatically selects the **highest conformance level** for the Archive as PDF/A workflow chosen.** For example, if you choose to convert to PDF/A-2 using the Archive as PDF/A-2 workflow, the Conversion Service converts to PDF/A-***2a*** where possible, which is the highest conformance level for PDF/A-2. The generated file is also compatible with PDF/A-2b (basic) and PDF/A-2u (Unicode) specifications. For more information on conformance levels, see [PDF/A - The standard for archiving](https://www.pdf-tools.com/public/downloads/whitepapers/whitepaper-pdfa-standard-iso-19005-en.pdf). Generally speaking, the processing steps for all Archive as PDF/A workflows are identical. All input documents of a job are processed as follows: **PDF/A workflow steps** 1. **Analyze file type** — The documents are analyzed. If the file type of any document is unsupported, conversion is aborted. Otherwise, they are sent to the next processing step depending on their file type. 1. **Validate and repair PDF (Quality Assurance)** — To ensure document quality, PDF and PDF/A documents are validated. If a corruption is detected, the Conversion Service attempts to repair it. 1. **Convert to PDF** — Non-PDF documents (e.g. images, Office documents) are converted to PDF if their format is supported by the Conversion Service. 1. **Perform OCR** — To make the resulting document searchable, OCR is performed on documents that require it. The recognized text is stored directly in the PDF. *Note: This is an optional step and can only be enabled with an appropriate license.* 1. **Apply stamping** — Stamps such as barcodes, text stamps, image stamps, or placeholders are added. 1. **Convert to PDF/A** — PDF documents that are not already PDF/A-conforming are converted to a high-quality PDF/A. The actions performed in this step vary for PDF/A-1, PDF/A-2, and PDF/A-3. 1. **Merge / Collect** — The converted documents of a job are merged or collected into a single document, depending on the profile setting. 1. **Optimize** — The resulting document is compressed and optimized for archiving. Redundant and unnecessary data is removed, images are compressed intelligently, and fonts are merged and subset. *Note: This is an optional step and can only be enabled with an appropriate license.* 1. **Sign** — The resulting document is digitally signed using the signature settings in the selected profile. *Note: This is an optional step and can only be enabled with an appropriate license.* ## Archive as TIFF The **[Archive as TIFF](https://www.pdf-tools.com/docs/conversion-service/workflows/tiff)** workflow is engineered specifically to prepare documents for archiving in suitable TIFF format. ## Convert to PDF The **[Convert to PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion)** is engineered for converting documents to PDF. Files are converted to standard PDF (not PDF/A), the file format is not validated, and the output documents cannot be signed. OCR is available as an optional processing step. ## Convert to XML The **[Convert to XML workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/convert-to-xml)** is engineered specifically to extract searchable text from documents and output the results as structured XML. Unlike the Extraction workflow, which extracts existing embedded text data from PDFs, the Convert to XML workflow processes all input documents to generate text data in XML format. ## Create Dossier PDF The **[Create Dossier PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier)** is specifically designed to compile multiple PDF documents into a single dossier. All PDF document supplied to the job are merged into a single PDF in the order that they were added to the job. ## Extract XML from PDF The **[Extract XML from PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/extraction)** outputs an XML file containing the extracted OCR data or an empty `` tag if no embedded OCR data is found. ## Prepare Invoice PDF The **[Prepare Invoice PDF workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/invoice)** is engineered specifically for preparing invoices. This workflow converts a main document to PDF/A-3 and attaches one or more files to the result. For example, to a PDF invoice an Excel table containing additional data can be attached. ## Sign PDF The **[Sign PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/sign)** workflow is engineered specifically for signing archived documents without removing the existing signatures. ## Enabling workflows You can enable or disable the workflows available in the Conversion Service Configurator, in the **Workflows & Profiles** tab by clicking the toggle button right next to the workflow name. Your changes are kept in memory until you click **Save & Restart Service**. --- ## Convert to PDF workflow :::info[Workflow identifier] This workflow is identified as **Conversion** in the Conversion Service. This workflow is engineered specifically for converting documents to PDF 1.x. Unlike the Archive as PDF/A workflows, files are only converted to PDF (and not PDF/A), the file format is not validated and the output documents cannot be signed. The Convert to PDF workflow supports the following features: - Compression and optimization for speed or size - Optical character recognition (OCR) - Office file conversion (as required) - Configuration of attachment conversion ## Supported file formats for Convert to PDF workflow The Convert to PDF workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) | ## Configure the workflow The workflow's profile provides detailed configuration options for file conversion processes. All processing steps can be enabled and customized within the [profile configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). The Convert to PDF workflow includes the following configurable features: - [Optimize for speed or size](#optimize-for-speed-or-size) - [Convert mode for child documents (attachments)](#convert-mode-for-child-documents-attachments) - [Collect mode](#collect-mode) ### Optimize for speed or size You can select whether to optimize files for: - **Speed**: Processing time - **Size**: Minimal document file size ### Convert mode for child documents (attachments) Certain child documents, such as attachments to emails or PDF documents, can be skipped (removed) during conversion to PDF. The convert mode can be specified based on the type of the child document, its filename, or the type of its parent document. For example, by default executables attached to an email are removed. If desired, rules can be added to attach files that cannot be converted (for example PDF documents containing unrendered XFA, HTML documents) in their original source format to the resulting output document. ### Collect mode The collect mode configuration defines how a converted document and its child documents are combined. The collect mode can be configured for each document type and also defines how errors are handled. For example, emails can be converted by creating a PDF collection (portfolio) of their bodies and attachments. When converting Word documents, all embedded files can be merged into the converted PDF. ### Linearization Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web. The Conversion Service doesn't support linearization of attached documents (child documents). **info: Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.** ## Events The Convert to PDF workflow can generate the following events during processing. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `Generic` | Unclassified event. | | `CorruptionRepaired` | Corrupt document repaired automatically. | | `ContentRecovered` | Parts of a corrupt document's content recovered. | | `ExternalResourceUnavailable` | External resource couldn't be reached. | | `ContentClipped` | Content cut off because it doesn't fit the page size. | | `ContentOverflow` | Content overflowed into the page margin. | | `HtmlMultimediaRemoved` | Removed HTML multimedia elements. | | `VisualDifferences` | Conversion resulted in visual differences. | | `SignatureRemoved` | Removed cryptographic signatures. | | `NotLinearized` | PDF linearization was omitted. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the Convert to PDF workflow The Convert to PDF workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.AUTHOR` | The author of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.TITLE` | The title of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.SUBJECT` | The subject of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.KEYWORDS` | Keywords that apply to the document | | Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Convert to XML workflow Learn how to automatically extract text data from documents, images, and office files as structured XML. The Convert to XML workflow is engineered specifically to extract searchable text from documents and output the results as structured XML. ## Supported file formats for Convert to XML workflow The Convert to XML workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | PDF formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, ZIP (without password protection) | :::caution[Format-specific limitations] Some file formats have specific limitations when used with the Convert to XML workflow: - **OpenOffice formats**: PDF conversion depends on rendering in Microsoft Word, Excel, or PowerPoint. The conversion can result in visual differences in tables and tabs. Visual differences caused by differences in shape rendering are usually unacceptable. - **HTML**: Documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout. JavaScript content is disabled during processing. - **XML input files**: The Convert to XML workflow can't process XML files. If you submit an XML file to this workflow, it generates an error. The conversion of most file formats is enabled by default in the profile's Convert mode for child documents (attachments). ## Features and limitations Compared to the other workflows, this workflow has the following features and limitations: ### Resolution settings You can configure the resolution (in DPI) used when converting PDF pages to TIFF images. Higher resolution values produce more detailed images, which can improve text recognition accuracy but increase processing time. ### Collect mode All documents processed in a job are merged together before text extraction. The **Merge** collect mode is used to combine documents and their child documents. ## Configure the workflow The workflow's profile provides detailed configuration options for the conversion and text extraction processes. All processing steps can be enabled and customized within the [profile configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles). The Convert to XML workflow includes the following configurable features: - [Convert mode for child documents (attachments)](#convert-mode-for-child-documents-attachments) - [Collect mode](#collect-mode) - [Image resolution](#resolution-settings) ### Convert mode for child documents (attachments) Certain child documents, such as attachments to emails or PDF documents, can be skipped (removed) during conversion. The convert mode can be specified based on the type of the child document, its filename, or the type of its parent document. For example, by default executables attached to an email are removed. **info: XML files are explicitly excluded from conversion in this workflow. If the workflow encounters an XML file as a child document, it generates an error.** ### Collect mode The collect mode configuration defines how a converted document and its child documents are combined. The collect mode can be configured for each document type and also defines how errors are handled. For example, emails can be converted by merging their bodies and attachments. When converting Word documents, all embedded files can be merged into the converted PDF. ## Job and document options for the Convert to XML workflow The Convert to XML workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Document options Document options apply only to a specific input. It lets you specify properties for an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Create Dossier PDF workflow :::info[Workflow identifier] This workflow is identified as **Dossier** in the Conversion Service. Learn how to merge multiple PDFs into a single file using the Create Dossier PDF workflow. This process is designed to combine several PDF documents into one cohesive dossier. The PDFs are merged in the order that users provide them. Key features of the Create Dossier PDF workflow include: - Fully customizable title page, including its title, subtitle, and background. - Extensively customizable table of contents. - Bookmarks to add navigation and structure to the dossier. - Stamping options such as watermarks, headers, or footers. - Optional: Conversion to PDF/A. ## What is a dossier? A PDF **dossier** is a structured compilation of multiple documents merged into a single PDF file. The dossier often includes a table of contents, outline (document bookmarks), and metadata for easy navigation and organization. It is frequently used in business, legal, academic, and government contexts to present information in a clear, professional, and accessible format. ## Supported file formats for Create Dossier PDF workflow This workflow takes PDF files as input. To use other document formats, convert them to PDF using a **preprocessing** step in the Create Dossier PDF workflow, which points to another workflow that performs the preprocessing conversion. ## Add a title page You can configure this workflow to create a title page for the dossier. The title page contains the dossier's title and subtitle. The font, size, placement, and alignment of the text are fully configurable. Additionally, you can configure a PDF document to be used as a custom background for the title page. You can customize the title page for each job using the [`DOSSIER-TITLE`](#job-options) and [`DOSSIER-SUBTITLE`](#job-options) job options. ## Structure the dossier If the title from the metadata is not suitable, it can be overridden by using the [`DOCUMENT-TITLE`](#job-options) option. To organize the dossier effectively, you can create a [Table of Contents](#create-the-table-of-contents) and a [document outline](#create-the-document-outline) (bookmarks). By default, each document's title is derived from its metadata. If the metadata title is not suitable, you can override it using the [`DOCUMENT-TITLE`](#job-options) option. ### Create the table of contents The **table of contents (TOC)** provides an overview of the dossier's structure, making it easier to navigate. By default, the TOC follows the existing outline structure tree of the input documents and supports multiple configurable nesting levels. Optionally, you can create a parent entry for each input document. Customization options include: - **For the entire job**: Use the [`TOC-TITLE`](#job-options) option to define a custom title for the table of contents. - **For individual input documents**: Use the [`ADD-DOCUMENT-TOC-ITEM`](#document-options) option to include a document in the TOC and [`DOCUMENT-TOC-TITLE`](#document-options) to set its title. ### Create the document outline The **document outline** (also known as **bookmarks**) allows users to quickly navigate to specific sections of the dossier. By default, the Create Dossier PDF workflow uses the outline structure of the input documents. Additionally, a parent bookmark can be generated for each document if needed. Customization options include: - **For the entire job**: Use the [`TOC-OUTLINE-TITLE`](#job-options) option to set a custom title for the document outline. - **For individual input documents**: Use the [`ADD-DOCUMENT-OUTLINE`](#document-options) option to include a document in the outline and [`DOCUMENT-OUTLINE-TITLE`](#document-options) to set its title. ## Add stamps Review a general overview of stamping in [Stamp and annotation](https://www.pdf-tools.com/docs/conversion-service/workflows/stamping) documentation. You can further customize stamps for the Create Dossier PDF workflow using the `DOCUMENT-STAMP-TITLE` option or using a custom option `CUSTOM.OPTION_NAME`. For more information about this customization, review [Placeholders](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping#placeholders) section in stamping documentation. In the profile configuration, you can also choose to apply stamps to the table of contents pages or leave them without stamps. ## Example of the Create Dossier PDF workflow This example uses the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) to create a dossier from a cover page and two chapters. For the second chapter, the name of the bookmark is explicitly overridden. ``` C:\Temp>pdfclient -v -w Dossier -do ADD-DOCUMENT-OUTLINE false ^ chapter-1.pdf -do DOCUMENT-OUTLINE-TITLE "Chapter 2: XYZ" chapter-2.pdf out.pdf Creating job (id job1_5g5fkycbhhe) Adding file ".\chapter-1.pdf" (id jgvmhpyquh0) Adding file ".\chapter-2.pdf" (id 4ogify1xd31) Output: "out.pdf" - Info: Assembled PDF files 'chapter-1.pdf' and 'chapter-2.pdf' into dossier 'out.pdf'. ``` ## Events The Create Dossier PDF workflow can generate the following events during processing, plus any events from the dynamically invoked preprocessing workflow. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `SignatureRemoved` | Removed cryptographic signatures. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the Create Dossier PDF workflow The Create Dossier PDF workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. For any subsequent jobs processed with the workflow profile, use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | **[Title page](#add-a-title-page)** | `DOSSIER-TITLE` | Adds a title page with a title for the dossier. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. | | **[Title page](#add-a-title-page)** | `DOSSIER-SUBTITLE` | Adds a title page with a subtitle for the dossier. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. | | **[Table of contents](#create-the-table-of-contents)** | `TOC-TITLE` | Sets the heading for the table of contents. This option overrides the value specified in the profile configuration. The option should only be set at the job level and is ignored at the document level. | | **[Table of contents](#create-the-table-of-contents)** | `ADD-DOCUMENT-TOC-ITEM` | Creates a table of contents entry for each document included in the job. It can also be set at document level. `true` (default): entry in the table of contents is added for the input document. Existing bookmarks of the input document are added as sub-entries. `false`: The existing bookmarks of the input document are added directly to the top level of the table of contents. This can be useful in the following use cases: Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. | | **[Document outline](#create-the-document-outline)** | `ADD-DOCUMENT-OUTLINE` | Adds an outline (bookmark) for all documents in the job. `true` (default): A new bookmark is added to the document outline for the input document. Existing bookmarks of the input document are preserved and added as children to the newly created bookmark.`false`: The existing bookmarks of the input document are added directly to the top level of the document outline. This can be useful in the following use cases:Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. | |**[Document outline](#create-the-document-outline)** | `TOC-OUTLINE-TITLE` | Sets the title for the outline. The name of the bookmark created for the table of contents (if enabled). If it is omitted, one of the following values is used instead (in order of precedence): The value of the `TOC-TITLE` option.The title of the table of contents is configured in the profile. `TOC-OUTLINE-TITLE` should only be set at the job level and cannot be configured in the profile configuration. | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.AUTHOR` | The author of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.TITLE` | The title of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.SUBJECT` | The subject of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.KEYWORDS` | Keywords that apply to the document | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document rather than as a global setting (either determined by the job or the profile). For any subsequent jobs processed with the workflow profile, use the profile's default settings. | Type | Option | Description | | ----- | ------- | --- | | **[Document property](#structure-the-dossier)** | `DOCUMENT-TITLE` | Sets the title for the document by overriding the title determined by the [metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata). If no title is set in the metadata, `DOCUMENT-TITLE` is used for the table of contents, document outline, and stamp placeholder. It can be overridden by the `DOCUMENT-OUTLINE-TITLE`, `DOCUMENT-TOC-TITLE`, and `DOCUMENT-STAMP-TITLE` options. If it is omitted and no other specific option is set, one of the following values is used instead (in order of precedence):The document title from the document metadata.The filename of the input document (without the extension). This option should only be set at the document level and cannot be configured in the profile configuration. | | Document property | `DOC.PASSWORD` | Set the password for the document. | | **[Document outline](#create-the-document-outline)** | `ADD-DOCUMENT-OUTLINE` | Adds an outline (bookmark) for the specified document only, rather than all documents in the job. `true` (default): A new bookmark is added to the document outline for the input document. Existing bookmarks of the input document are preserved and added as children to the newly created bookmark.`false`: The existing bookmarks of the input document are added directly to the top level of the document outline. This can be useful in the following use cases:Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. | | **[Document outline](#create-the-document-outline)** |`DOCUMENT-OUTLINE-TITLE` | Sets the name of the bookmark in the dossier outline. If this option is omitted, one of the following values is used instead (in order of precedence):The value of the `DOCUMENT-TITLE` option.The document title from the document metadata.The filename of the input document (without the extension). This option should only be set at the document level and cannot be configured in the profile configuration. | | **[Table of contents](#create-the-table-of-contents)** | `ADD-DOCUMENT-TOC-ITEM` | Adds an entry in the table of contents for the specified document only, rather than all documents in the job. It can also be set at job level. `true` (default): entry in the table of contents is added for the input document. Existing bookmarks of the input document are added as sub-entries. `false`: The existing bookmarks of the input document are added directly to the top level of the table of contents. This can be useful in the following use cases: Special input documents that don't represent a chapter in the output document, such as a cover sheet or table of contents.Documents that already contain all necessary bookmarks. | | **[Table of contents](#create-the-table-of-contents)** | `DOCUMENT-TOC-TITLE` | Sets the name of the entry in the table of contents for the specified document. If this option is omitted, one of the following values is used instead (in order of precedence):The value of the option `DOCUMENT-TITLE`.The document title from the document metadata.The filename of the input document (without the extension).This option should only be set at the document level and cannot be configured in the profile configuration. | | **[Stamp options](#add-stamps)**| `DOCUMENT-STAMP-TITLE` | Sets the title of the document used for stamping, for example, for the `[input:DOCUMENT.TITLE]` placeholder (if used). If this option is omitted, one of the following values is used as placeholder value instead (in order of precedence): The value of the option `DOCUMENT-TITLE`.The document title from the document metadata.The filename of the input document (without the extension).This option should only be set at the document level and cannot be configured in the profile configuration. Accepts [placeholders](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping#placeholders). | | **[Stamp options](#add-stamps)** | `CUSTOM.OPTION_NAME` | Options whose name starts with **`CUSTOM.`** define custom placeholder variables that can be used with the placeholder format. See [Placeholders](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping#placeholders). | --- ## Error and event codes When the Conversion Service processes a job, it returns two types of feedback in the job result: an `error` object if the job fails, and an `events` array for non-fatal issues. The REST API response has the following structure: ```json { "status": "success", "error": { "code": "internal", "message": "string" }, "events": [ { "code": "ExternalResourceUnavailable", "severity": "info", ... "message": "string", } ], ... } ``` - The `error.code` field identifies the error type (refer to [Error codes](#error-codes)). - Each entry in the `events` array has a `code` field that identifies the event type (refer to [Event codes](#event-codes)). **info: For more information about the response structure, refer to [Get Job Result](https://www.pdf-tools.com/docs/conversion-service/api/advanced-api/get-job-result#responses).** ## Error codes When a job fails, the error object contains one of the following codes: | Code | Description | | --- | --- | | `internal` | Internal processing error. | | `configuration` | Configuration error. | | `generic` | Unclassified error. | | `unsupportedFormat` | Input format not supported. | | `unsupportedFeature` | Unsupported feature encountered. | | `option` | Invalid option or parameter. | | `canceled` | Job was canceled. | | `timeout` | Operation timed out. | | `password` | Password-related error, for example an encrypted document. | | `conformance` | PDF conformance requirement violation. | | `corrupt` | File corruption detected. | | `external` | External service or resource error. | ## Event codes Event codes identify event types returned in the API response. Events report informational messages, warnings, or errors encountered during processing. The `severity` field indicates the level of each event: `info`, `warning`, or `error`. ### Document integrity These events indicate issues with the integrity of the input document, such as corruption or missing content. | Code | Applies to | Description | | --- | --- | --- | | `Generic` | All formats | An event that doesn't match any other type. The `message` field provides additional details. | | `CorruptionRepaired` | All formats | A corrupt document was repaired automatically. Because each viewer has its own heuristics for repair, the repaired document might have visual differences. Examples: document damaged during upload, or created by an erroneous application. | | `ContentRecovered` | PDF, HTML/email, Office | Parts of a corrupt document's content were recovered. The output may be incomplete or contain visual differences. Review the output manually. Examples: damaged document, invalid image URL in email, wrong MIME part reference, incorrect text encoding. | ### External resources These events occur when the document references external resources that can't be retrieved during conversion. | Code | Applies to | Description | | --- | --- | --- | | `ExternalResourceUnavailable` | HTML/email, Office | An external resource couldn't be reached. Examples: an external image in an HTML email replaced with a placeholder because it wasn't found or the download timed out, content removed from an inaccessible external file in an Office document. Possible causes: no internet access, firewall block, resource doesn't exist. | ### Content layout These events indicate that document content didn't fit the configured page dimensions. | Code | Applies to | Description | | --- | --- | --- | | `ContentClipped` | HTML/email | Document content was cut off because it doesn't fit the page size. Examples: fixed-size table larger than page width, deeply indented list. | | `ContentOverflow` | HTML/email | Content overflowed into the page margin, but no content was lost. Controlled by the default page size and default page margin settings. Examples: fixed-size table wider than the content area but fitting within the margin. | ### Visual fidelity These events indicate that the output may look different from the original document. | Code | Applies to | Description | | --- | --- | --- | | `ContentRasterized` | PDF, Image | Page content was converted to an image to enable conversion of non-convertible content, for example during PDF/A conversion. | | `PageRenderer` | PDF, Image | A page was removed from the document because it couldn't be converted to an image. | | `VisualDifferences` | PDF, HTML/email, Office | Conversion resulted in visual differences. Examples: proprietary annotation appearance couldn't be generated, numbers exceeded allowed range, ambiguous font-to-glyph mapping. | | `Colorants` | PDF | Resolved ambiguous or conflicting spot color descriptions. Colorants are special inks (for example, PANTONE). Conflicting descriptions are harmonized during PDF/A conversion. No effect on devices where the colorant is available. | | `TransparencyRemoved` | PDF | Transparent objects were converted to opaque, as required for PDF/A-1. May cause visual differences. Recommendation: use PDF/A-2 or higher, which allows transparency. | | `FontSubstituted` | PDF, HTML/email, Office | A required font wasn't embedded or installed, so a similar font was substituted. May cause minor visual differences, but all text is preserved. Ensure recommended fonts are installed. | ### Metadata and structure These events indicate that metadata or logical structure information was modified or removed to meet the target format requirements. | Code | Applies to | Description | | --- | --- | --- | | `MetadataRemoved` | PDF | Metadata properties (for example, XMP metadata) were removed because they didn't conform to the target standard. | | `StructureRemoved` | PDF | Logical structure (tagging) information was removed because it was invalid or corrupt. Tagging provides accessibility information such as reading order. Generated only when tagging must be removed due to invalidity, not when removed by request. | | `NotLinearized` | PDF | PDF linearization was omitted. Linearization enables incremental download and viewing. This is safe and doesn't affect content or validity. Example: linearization would increase file size beyond the configured threshold. | ### Removed features These events indicate that interactive or embedded content was removed to meet the target format requirements. Visual appearance is generally preserved, but interactivity is lost. | Code | Applies to | Description | | --- | --- | --- | | `LayersRemoved` | PDF | Removed optional content groups (layers). Doesn't change initial page appearance, but content visibility can no longer be toggled. Example: layers removed during PDF/A-1 conversion. | | `AnnotationRemoved` | PDF | Removed annotations. Doesn't cause visual differences, but removes interactivity. Examples: removed proprietary or forbidden annotation types during PDF/A conversion. | | `MultimediaRemoved` | PDF | Removed multimedia content (sound, movie). Doesn't cause visual differences, but removes interactivity. Example: removed movie during PDF/A conversion. | | `HtmlMultimediaRemoved` | HTML/email | Removed HTML multimedia elements (iframe, embed, source, audio, video). May cause visual differences and removes interactivity. | | `ActionRemoved` | PDF | Removed prohibited action types. Doesn't cause visual differences, but removes interactivity. Example: removed JavaScript actions in form fields during PDF/A conversion. | | `SignatureRemoved` | PDF | Removed cryptographic signatures from a signed document. Visual appearances are preserved. Examples: merged signed PDFs, converted a signed document to PDF/A, optimized a signed document. | | `ChildRemoved` | All formats | Removed a child element from a container. Examples: removed an embedded file from a PDF, removed a file from a ZIP archive, removed an attachment from an email. | ### OCR These events indicate issues with optical character recognition processing. | Code | Applies to | Description | | --- | --- | --- | | `OcrIncomplete` | PDF, Image | Unable to perform optimal OCR recognition. Examples: optimal resolution not within configured range, required fonts for OCR text not installed. | | `UnicodesIncomplete` | PDF, Image | Unable to make text fully extractable. Critical when text processing mode is set. Example: unable to add Unicode information to a font. | | `TaggingIncomplete` | PDF, Image | Unable to generate complete tagging information. Critical for accessibility tagging of scans. Doesn't mean no OCR text was added, only that tagging had issues. Can generally be ignored unless accessibility compliance is required. | ## Configure event behavior You can configure how each event is handled in the workflow profile using the Configurator. In the **Workflows & Profiles** section, select a profile and open the **Events** settings. Each event has three options: - **Warning** (default): The job continues and logs a warning. - **Error**: The job fails if this event occurs. - **Ignore**: The event is silently suppressed. The Configurator groups events by category: --- ## Extract XML from PDF workflow :::info[Workflow identifier] This workflow is identified as **Extraction** in the Conversion Service. This workflow extracts XML data containing the extracted OCR information from PDFs. If no embedded OCR information is found, the Extract XML from PDF workflow outputs an empty `` tag. The workflow supports these features: - Extraction of OCR-related XML information from PDF documents - Simple configuration with minimal options - Outputs XML with document data or an empty `` tag if no embedded OCR data is found ## Supported file formats for Extract XML from PDF workflow This workflow supports these file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | PDF formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | **info: If the input PDF does not contain embedded OCR data, the workflow outputs an XML file with an empty `` tag.** ## Job options for the Extract XML from PDF workflow The Extract XML from PDF workflow lets you use [job options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job-specific values for use when processing documents. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Prepare Invoice PDF workflow :::info[Workflow identifier] This workflow is identified as **Invoice** in the Conversion Service. This workflow is engineered specifically for preparing invoices. This workflow converts a main document to PDF/A-3 and attaches one or more files to the result. For example, you can attach an Excel table containing additional data to a PDF invoice. The workflow supports the following features: - Conversion to PDF/A-3 format - Additional document attachments - Office conversion (optional) - Digital signatures (optional) ## Supported file formats for Prepare Invoice PDF workflow This workflow supports PDF and MS Word as input formats. **note: If you want support for formats such as ZUGFeRD, let us know through the [Contact page](https://www.pdf-tools.com/contact/).** ## Convert to PDF/A-3 This workflow has been optimized for the conversion of transactional documents. It supports conversion of Word and PDF documents to PDF/A-3. ## Attach documents To attach additional documents to a main document, all documents must be added to a single job. The documents to attach and additional properties can be set using the [`DOC.ROLE`](#document-options), [`AF.RELATIONSHIP`](#document-options), [`AF.MODDATE`](#document-options), and [`AF.DESCRIPTION`](#document-options) document options. These values are written into the result document and are visible to a user in the list of attached documents. ## Example of the workflow This example uses the [shell client](https://www.pdf-tools.com/docs/conversion-service/integrate/shell-client) to attach `supplement.xls` to the main document `invoice.docx`. Note that the `-do ‹name› ‹value›` option applies a document option to the subsequent input file. ``` C:\Temp> pdfclient -v -w Invoice invoice.docx ^ -do DOC.ROLE attached -do AF.RELATIONSHIP Supplement supplement.xls ^ out.pdf Creating job (id job123_4q5mprmmrz0) Adding file "invoice.docx" (id 0kk1ddv0uzg) Adding file "supplement.xls" (id 2fg4ufg3qmz) Output: "invoice.pdf" - Info: Converted Word document 'invoice.docx' to PDF. - Info: Converted 'invoice.pdf' to PDF/A-3u. - Info: Attached file 'supplement.xls' to 'invoice.pdf'. ``` ## Events The Prepare Invoice PDF workflow can generate the following events during processing. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `CorruptionRepaired` | Corrupt document repaired automatically. | | `ContentRecovered` | Parts of a corrupt document's content recovered. | | `VisualDifferences` | Conversion resulted in visual differences. | | `Colorants` | Resolved ambiguous or conflicting spot color descriptions. | | `LayersRemoved` | Removed optional content groups (layers). | | `TransparencyRemoved` | Transparent objects converted to opaque. | | `ChildRemoved` | Removed a child element from a container. | | `MetadataRemoved` | Removed non-conforming metadata properties. | | `SignatureRemoved` | Removed cryptographic signatures. | | `FontSubstituted` | Substituted a missing font. | | `AnnotationRemoved` | Removed annotations. | | `MultimediaRemoved` | Removed multimedia content. | | `ActionRemoved` | Removed prohibited action types. | | `StructureRemoved` | Removed invalid or corrupt logical structure (tagging). | | `ContentRasterized` | Page content converted to an image. | | `PageRenderer` | A page was removed because it couldn't be converted. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the Prepare Invoice PDF workflow The Prepare Invoice PDF workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. Type | Option | Description | | --- | ---- | --- | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.AUTHOR` | The author of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.TITLE` | The title of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.SUBJECT` | The subject of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.KEYWORDS` | Keywords that apply to the document | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Required | Description | |----------------------|--------------------|-----------|-------------| | [Attach documents](#attach-documents) | `DOC.ROLE` | **Required** | Defines the document's role. Supported values are: `main` (default): The main document. Each job must have one main document.`attached`: A document attached to the main document. Multiple attached documents may exist in a job. | | [Attach documents](#attach-documents) | `AF.RELATIONSHIP` | **Optional** | Defines the relationship of the attached document to the main document. Supported values are: `Unspecified` (default): Used when the relationship is unknown or cannot be described using the other values.`Source`: The attached document is the original source material for the main document.`Data`: The attached document represents information used to derive a visual presentation (for example table or graph).`Alternative`: The attached document is an alternative representation of content, such as audio.`Supplement`: The attached document provides a supplemental version of the original source or data that is more easily consumable (for example a MathML version of an equation). | | [Attach documents](#attach-documents) | `AF.MODDATE` | **Optional** | Defines the date and time when the attached document was last modified. For example: `"2009-05-19T09:15:22.0000000+02:00"` | | [Attach documents](#attach-documents) | `AF.DESCRIPTION` | **Optional** | Descriptive text associated with the attached document. | | Document property | `DOC.PASSWORD` | **Optional** | Sets the password for the document. | --- ## Metadata in workflows Learn how to customize the metadata of the converted PDFs. This feature is available in all workflows. **note: Metadata are applied only to the main result document and not to embedded files or any other contained documents.** Set all runtime options for further customizing the metadata at the job level, not at the document level. ## Standard properties The four standard PDF metadata properties that can be customized are **Author**, **Title**, **Subject**, and **Keywords**. You can configure a fixed value in the profile configuration for each of these mentioned properties. If no value is configured, the original value is preserved (if available). You can also provide the values dynamically using the following job options: | Option | Description | |---|---| | `META.AUTHOR` | The author of the document. | | `META.TITLE` | The title of the document. | | `META.SUBJECT` | The subject of the document. | | `META.KEYWORDS` | Keywords that apply to the document. | ## Extended properties Extended metadata is defined by the XMP standard, with properties grouped into schemas. The Conversion Service allows setting XMP property values from the following schemas: - **Dublin Core schema** - **XMP Basic schema** - **XMP Rights Management** - Your custom extension schema **tip: You can find all the specific schemas and their respective properties in the Conversion Service Configurator:** 1. Open the Conversion Service Configurator, and then click **Workflow & Profiles**. 1. Select a profile where you would like to configure the properties. and then click the pen icon next to it to open the profile configuration. 1. Scroll to **Metadata** to review or change available properties. ### Dublin Core schema The Dublin Core schema provides a set of commonly used properties. Values can be configured statically for each profile in the configurator or dynamically using the following job options: | Option | Description | |---|---| | `META.EXT.DC.CONTRIBUTOR` | Contributors to the resource (excluding the authors).*Note: Although the schema technically supports multiple values, you can only set a single value.* | | `META.EXT.DC.COVERAGE` | The extent or scope of the resource. | | `META.EXT.DC.IDENTIFIER` | A unique identifier of the resource. | | `META.EXT.DC.RIGHTS` | Informal rights statement. | | `META.EXT.DC.SOURCE` | Unique identifier of the work from which this resource was derived. | | `META.EXT.DC.TYPE` | A document type. For example **novel**, **poem**, or **working paper**.*Note: Although the schema technically supports multiple values, you can only set a single value.* | ### XMP Basic schema The XMP Basic schema contains properties that provide basic descriptive information. Values can be configured statically for each profile in the configurator or dynamically using the following job options: | Option | Description | |---|---| | `META.EXT.XMP.NICKNAME` | A short informal name for the resource. | | `META.EXT.XMP.LABEL` | A word or phrase identifying a document as part of a user-defined collection. Useful for organizing documents in a file browser. Note: *This property is not available in PDF/A-1* | | `META.EXT.XMP.RATING` | A number indicating a document's status relative to others. Used for organizing documents in a file browser. Values are user-defined within an application-defined range. Note: *This property is not available in PDF/A-1* | ### XMP Rights Management schema This schema includes properties related to rights management. Values can be configured statically for each profile in the configurator or dynamically using the following job options: | Option | Description | |---|---| | `META.EXT.XMP-RIGHTS.CERTIFICATE` | URL of an online rights management certificate. | | `META.EXT.XMP-RIGHTS.MARKED` | Indicates that this is a rights-managed resource. | | `META.EXT.XMP-RIGHTS.OWNER` | The legal owner of the resource. Note: *Although the schema technically supports multiple values, you can only set a single value.* | | `META.EXT.XMP-RIGHTS.USAGE-TERMS` | Text instructions on how the resource can be legally used. | | `META.EXT.XMP-RIGHTS.WEB-STATEMENT` | URL of a webpage describing the owner or rights statement for this resource. | ### Custom extension schemas For metadata properties not covered by predefined schemas, you can define a custom schema. Provide the schema definition in the profile configuration with the following steps: 1. Open the Conversion Service Configurator, and then click **Workflow & Profiles**. 1. Select a profile where you would like to configure your own schema, and then click the pen icon next to it to open the profile configuration. 1. Scroll at the end of the **Metadata** section, and then find the **Custom Extension Schemas**. 1. Click **Add item**, and then click **Next**. 1. Fill in the information as you require for your custom schema. **note: Keep the XMP extension schemas stable over time. ** If incompatible changes are necessary, create a new schema instead. You can configure the specific property values statically or dynamically using a placeholder and the following custom job and document option: Document and job option Placeholder description Placeholder example `CUSTOM.OPTION_NAME` No default value provided: `[custom:OPTION_NAME]` this makes the job and document option required. If the job and document option is not provided during processing, an error is raised. `[custom:REVIEWER]` Default value provided: `[custom:OPTION_NAME, 'DEFAULT_VALUE']` this makes the job and document option optional. If the corresponding job and document option is not provided during processing, the specified default value will be used. The single quotes (`'`) around the default value are a required in this syntax. `[custom:REVIEWER, 'John Doe']` Empty default value provided: `[custom:OPTION_NAME, '']` this makes the job and document option optional. If the corresponding job option is not provided during processing, no value will be set (the field will be left empty). Include empty single quotes as the default value (`''`). The single quotes (`'`) are required in this syntax. `[custom:REVIEWER, '']` ## Advanced usage For advanced users, you can further customize and refine the metadata using the following job option: | Option | Description | |---|---| | `META.XMP` | A complete XMP packet replacing the metadata of the input document.This option can set all kinds of metadata, including [standard properties](#standard-properties), [extended properties](#extended-properties), and [custom extension schemas](#custom-extension-schemas).Any properties set using standard mechanisms take precedence over values provided in this XMP packet. | **note: When creating a PDF/A document, the XMP metadata must include a complete schema definition for all custom extension schemas. This definition can be provided:** - Directly in the XMP packet. - Using [custom extension schema](#custom-extension-schemas) configuration, with the **Force Definition** setting enabled. --- ## Archive as PDF/A-1 workflow :::info[Workflow identifier] This workflow is identified as **Archive PDF/A-1** in the Conversion Service. This workflow is engineered specifically for preparing documents for archiving, specifically where PDF/A-2 or PDF/A-3 conformance is not allowed. This workflow is disabled by default because it is recommended you use [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) workflow for archiving. Since PDF/A-2 is based on a newer version of the PDF standard, more PDF features are allowed such as transparency, layers, embedded files, and a less restrictive internal file structure. For these reasons, achieve fewer conversion errors and better conversion quality with the Archive as PDF/A-2 workflow. Particularly, if you use the Conversion Service in a Docker container where document content rasterization is unavailable, use PDF/A-2 workflow instead to avoid visual differences, removed transparency, or other potential issues. **info: For more information on PDF/A-2, read [PDF/A-2 overview](https://www.pdf-tools.com/pdf-knowledge/all-about-pdf-a-long-term-archiving/).** ## Supported file formats for Archive as PDF/A-1 workflow The Archive as PDF/A-1 workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) | :::caution[Note on OpenOffice formats] PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel or PowerPoint. In particular, visual differences may occur with tables and tabs. The visual differences caused by the rendering of shapes are usually not acceptable. :::caution[Note on HTML format] HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout. JavaScript content is disabled during processing. :::caution[Note on XML format] Layout information and images need to be available on the web. The conversion of most file formats is enabled by default in the profile's Convert mode for child documents (attachments). ## Features and limitations Compared to the PDF/A-2 workflow, this workflow has the following features and limitations: ### Collect mode The PDF/A-1 standard does not allow embedded files. Therefore, the only collect mode configuration available is **Merge**. ### Document content rasterization Certain graphical features of PDF documents are not allowed in PDF/A-1; for example, transparency. The removal of such features can lead to severe visual differences that may render the page's content unreadable. The Windows version of the Conversion Service can preserve the visual appearance of such documents by converting the pages' content to images (content rasterization).When doing so, a *content rasterized* warning is generated. If possible, content rasterization preserves the pages' extractable text, links, outlines and viewer preferences. The Docker version cannot rasterize pages. Therefore, the conversion of such files leads to *transparency removed* or *visual differences* warning depending on whether the visual differences are caused by the removal of transparency. ### Sign Document signing is currently not implemented. ### Linearization Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web. The Conversion Service doesn't support linearization of attached documents (child documents). **info: Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.** ## Events The Archive as PDF/A-1 workflow can generate the same events as the [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2#events) workflow. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). The following events occur more frequently when converting to PDF/A-1 due to the stricter format requirements than for the newer archive formats: - `AnnotationRemoved` - `ContentRasterized`: Generated only on the Windows version of the product, where content rasterization is available. - `LayersRemoved` - `TransparencyRemoved`: Generated only on Docker, where content rasterization is unavailable. - `VisualDifferences` To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the PDF/A-1 workflow The PDF/A-1 workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. Type | Option | Description | | --- | ---- | --- | | Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format | | OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.AUTHOR` | The author of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.TITLE` | The title of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.SUBJECT` | The subject of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.KEYWORDS` | Keywords that apply to the document | | Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Archive as PDF/A-2 workflow :::info[Workflow identifier] This workflow is identified as **Archive PDF/A-2** in the Conversion Service. The Archive as PDF/A-2 workflow is engineered to prepare documents for archiving. In particular, you can: - Maintain the original appearance and structure of the document. - Minimize the loss of information. - Ensure traceability and reproducibility of the changes made to the document. The Archive as PDF/A-2 workflow supports the following features: - Conversion to PDF/A-2 format (PDF/A-2b, PDF/A-2u, and PDF/A-2a) - Optimization of PDF/A structure (optional) - Office conversion (optional) - Optical character recognition (optional) - Digital signatures (optional) :::info[Conformance levels] The Conversion Service supports Basic (PDF/A-2b), Unicode (PDF/A-2u), and accessibility (PDF/A-2a) conformance levels. All conformance levels are incremental; the subsequent conformance level includes the requirements of the previous level and other additional requirements. For example, all level U (Unicode) PDF/A-2 documents are **valid level B (Basic) documents**. The Archive as PDF/A-2 workflow automatically tries to convert the input document to the **highest conformance level** for PDF/A-2 (usually PDF/A-2a). If the input document is PDF/A-2b or a PDF without structure information, the workflow tries to convert it to PDF/A-2u. If the workflow cannot convert to the PDF/A-2u conformance level, it converts to PDF/A-2b or ends the conversion with a failure. ## Supported file formats for Archive as PDF/A-2 The Archive as PDF/A-2 workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) | :::info[Note on OpenOffice formats] PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel, or PowerPoint. In particular, visual differences may occur with tables and tabs. Visual differences caused by the rendering of shapes are usually not acceptable. :::info[Note on HTML format] HTML documents must be self-contained (layout information and images are either embedded within documents or available online) and suited for portrait page layout. JavaScript content is disabled during processing. :::info[Note on XML format] Layout information and images must be available online. The conversion of most file formats is enabled by default in the Convert mode. ## Configure the workflow The Archive as PDF/A-2 workflow's profile provides detailed configuration options for converting files to the PDF/A-2 standard. The [profile configuration](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles) allows for the customization of all processing steps. **tip: To view the processing steps in the Archive as PDF/A workflows, see [PDF/A workflow steps](https://www.pdf-tools.com/docs/conversion-service/workflows/#archive-as-pdfa-workflows).** ### Convert mode for child documents (attachments) Define which documents the Archive as PDF/A-2 workflow converts (Convert option) and skips (removes) from the result using the **Convert mode for child documents (attachments)** configuration. When removing documents, the Conversion Service generates a warning (*Skip with Warning* option) or an informational message (*Skip* option). Using the Convert mode for child documents (attachments), you can define rules based on the child document type, its filename, or the type of its parent document. Based on these parameters, you can configure the Archive as PDF/A-2 workflow to convert, keep, or skip(remove) various child documents. For example, by default, the Archive as PDF/A-2 workflow converts Microsoft Office files to PDF/A, removes executables, and removes other non-convertible documents with a warning. ### Collect mode The collect mode defines how a converted document and its child documents are combined. The collect mode can be specified for each document type individually. There are two collect mode categories: - **Merge**: Merge the pages of multiple PDF files into a single document. - **Attach**: Attach (embedded) child documents into a PDF file. For example, you can configure the Archive as PDF/A-2 workflow to convert emails into a PDF collection (Portfolio) of their bodies and attachments. When converting Word documents, their embedded files can be attached to the converted PDF. A PDF collection (Portfolio) is a special case of the **Attach collect mode**, where the parent document contains no pages. Still, the resulting portfolio PDF displays a convenient table of the attached documents for easy navigation. The advantage of the Attach collect mode is that it can preserve all information of the input files and the files' structure. The **Merge collect mode** creates simple files that can be processed and viewed by all PDF applications. The disadvantage is that this mode can only merge PDF files. Furthermore, not all information can be preserved when merging PDF files. For example, document metadata, signatures, and certain interactive form fields cannot be merged and must be removed. Also, logical structure (tagging) information might be less meaningful after merging. The recommended collect mode configuration for the **Merge use case**: | Doc type | Collect mode | |---|---| | Job | Merge | | Word | Merge or Attach | | Excel | Merge or Attach | | PowerPoint | Merge or Attach | | Email | Merge or Attach | | Archive (ZIP) | Merge or Attach | | PDF | Preserve Structure | The recommended collect mode configuration for the **Attach use cases**: | Doc type | Collect mode | |---|---| | Job | Collection or single document | | Word | Attach | | Excel | Attach | | PowerPoint | Attach | | Email | Attach | | Archive (ZIP) | Collection or single document | | PDF | Preserve Structure | **tip: If necessary, the Flatten collect mode can be used for PDF files to flatten the structure of PDF documents. Up to version 3.1 of the Conversion Service, this has been the default behavior.** ### Child error handling This configuration defines how errors are handled during the conversion of child documents. In case of an error, the child document can either be skipped (removed) from the result and a warning generated (*Skip with Warning* option). Alternatively, the conversion of the parent document can be aborted with an error (*Strict* option). ### Linearization Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web. The Conversion Service doesn't support linearization of attached documents (child documents). **info: Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.** ## Events The Archive as PDF/A-2 workflow can generate the following events during processing. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `Generic` | Unclassified event. | | `CorruptionRepaired` | Corrupt document repaired automatically. | | `ContentRecovered` | Parts of a corrupt document's content recovered. | | `ExternalResourceUnavailable` | External resource couldn't be reached. | | `ContentClipped` | Content cut off because it doesn't fit the page size. | | `ContentOverflow` | Content overflowed into the page margin. | | `HtmlMultimediaRemoved` | Removed HTML multimedia elements. | | `VisualDifferences` | Conversion resulted in visual differences. | | `SignatureRemoved` | Removed cryptographic signatures. | | `NotLinearized` | PDF linearization was omitted. | | `Colorants` | Resolved ambiguous or conflicting spot color descriptions. | | `LayersRemoved` | Removed optional content groups (layers). | | `TransparencyRemoved` | Transparent objects converted to opaque. Rare for PDF/A-2 because the format allows transparency. | | `ChildRemoved` | Removed a child element from a container. | | `MetadataRemoved` | Removed non-conforming metadata properties. | | `FontSubstituted` | Substituted a missing font. | | `AnnotationRemoved` | Removed annotations. | | `MultimediaRemoved` | Removed multimedia content. | | `ActionRemoved` | Removed prohibited action types. | | `StructureRemoved` | Removed invalid or corrupt logical structure (tagging). | | `ContentRasterized` | Page content converted to an image. | | `PageRenderer` | A page was removed because it couldn't be converted. | | `OcrIncomplete` | Unable to perform optimal OCR recognition. | | `UnicodesIncomplete` | Unable to make text fully extractable. | | `TaggingIncomplete` | Unable to generate complete tagging information. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the PDF/A-2 workflow The PDF/A-2 workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. Type | Option | Description | | --- | ---- | --- | | Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format | | OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.AUTHOR` | The author of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.TITLE` | The title of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.SUBJECT` | The subject of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.KEYWORDS` | Keywords that apply to the document | | Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Archive as PDF/A-3 workflow :::info[Workflow identifier] This workflow is identified as **Archive PDF/A-3** in the Conversion Service. The Archive as PDF/A-3 workflow is engineered specifically for preparing documents for archiving. The features and processing steps are identical to the ([Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/#archive-as-pdfa-workflows)). However, the PDF/A-3 format allows additional features regarding embedded files. In particular, attachments that are not conforming to PDF/A. The unconverted original files are embedded as *Source* in the converted PDF. This allows for more flexibility, preserving the original file while still ensuring the document is archive-ready. The Archive as PDF/A-3 workflow supports the following features: - Conversion to PDF/A-3 format (PDF/A-3b, PDF/A-3u, and PDF/A-3a) - Compression and optimization of PDF/A structure (optional) - Office conversion (optional) - Optical character recognition (optional) - Digital signatures (optional) :::info[Conformance levels] The Conversion Service supports Basic (PDF/A-3b), Unicode (PDF/A-3u), and accessibility (PDF/A-3a) conformance levels. All conformance levels are incremental; the subsequent conformance level includes the requirements of the previous level and other additional requirements. For example, all level U (Unicode) PDF/A-3 documents are **also valid level B (Basic) documents**. The Archive as PDF/A-3 workflow automatically tries to convert to the **highest conformance level** for PDF/A-3 (usually, PDF/A-3a). If the input document is PDF/A-3b or a PDF without structure information, it tries to convert the document to PDF/A-3u. If it is unable to convert to this level, it converts to PDF/A-3b or ends in failure. ## Supported file formats for Archive as PDF/A-3 workflow The Archive as PDF/A-3 workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | Document formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) | :::info[Note on OpenOffice formats] PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel or PowerPoint. In particular, visual differences may occur with tables and tabs. The visual differences caused by the rendering of shapes are usually not acceptable. :::info[Note on HTML format] HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout. JavaScript content is disabled during processing. :::info[Note on XML format] Layout information and images need to be available on the web. The conversion of most file formats is enabled by default in the Convert mode. ## Configure the workflow The workflow's profile offers a fine-grained configuration of how files are converted. ### Convert mode for child documents (attachments) This extends the Convert mode of the [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2#convert-mode-for-child-documents-attachments) workflow with PDF/A-3 features. Specifically, the PDF/A-3 standard allows to embed child documents *As Is*, i.e. without converting them to PDF/A. For example, by default Office files are converted to PDF/A-3, images are used as-is, and executables are removed. ### Collect mode This is the same as the Collect mode of the [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2#collect-mode) workflow. However, in the PDF/A-3 workflow, it is common to choose the *As Is* Convert mode for some child document types. Therefore, the use of the **Merge** collect mode is strongly discouraged, because it is limited to PDF documents (review [Collect mode](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2#collect-mode)). Instead, the **Collection or Single Document** and **Attach** collect modes are recommended. Refer to the documentation panel of the Conversion Service Configurator for a detailed description of the available collect modes. ### Attach Source Document The source document (original document) can be attached. The configuration allows for each file type to decide if the source document should be attached or not. By default, the source documents for Office files are attached. Note that this may increase the file size of the result substantially. ### Attach Conversion Report All events of a conversion can be written to a report file and attached to the result document. ### Linearization Linearization internally restructures document content for faster loading and rendering in web browsers. However, linearization has trade-offs such as increased file size and a limited effect on rendering performance. Use PDF linearization when you need to load the first page of a PDF fast on the web. The Conversion Service doesn't support linearization of attached documents (child documents). **info: Although linearization provides fast, page-by-page loading over a network connection, it is not recommended for all use cases as it can considerably increase file size and has a limited effect.** ## Events The Archive as PDF/A-3 workflow can generate the same events as the [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2#events) workflow, with additional `ChildRemoved` scenarios for attachments. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the PDF/A-3 workflow The PDF/A-3 workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. Type | Option | Description | | --- | ---- | --- | | Document compression and optimization | `OPTIMIZE` | Turn on or off document compression and optimization. All settings must be previously set up in the profile. If `true`, documents included in the job are compressed and optimized according to the optimization profile set in the profile settings. If `false`, no compression and optimization is performed. Documents can be optimized according to five profiles:**Web**: Compresses the file without affecting viewing quality on digital devices**Print**: Compresses the file without affecting print quality**Max**: Removes redundant data and reduces image resolution to achieve a minimal viable file size**MRC**: Profile designed to process mixed raster content**Archive**: Prepares a document for archiving in PDF/A format | | OCR | `OCR` | Turn on and off optical character recognition for the job. All settings must be previously set up in the profile. If `true`, documents included in the job are processed to recognize any images as text (as appropriate). If `false`, no OCR is performed. | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.AUTHOR` | The author of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.TITLE` | The title of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.SUBJECT` | The subject of the document | | [Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata) | `META.KEYWORDS` | Keywords that apply to the document | | Document settings | `PDF.LINEARIZE` | Enable or disable linearization of the output PDF. | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (either determined by the job or the profile). Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Sign PDF workflow :::info[Workflow identifier] This workflow is identified as **Sign** in the Conversion Service. This workflow is engineered specifically for signing archived documents without removing the existing signatures. **tip: To learn about specific configuration options, review **[Configure signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/)** documentation.** The Sign PDF workflow supports the following features: - Digital Signature (mandatory) ## Supported file formats for Sign PDF workflow This workflow supports these file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | PDF formats | PDF/A-1, PDF/A-2, PDF/A-3 | :::caution[Note on PDF formats] Non-archival PDF formats are not supported. Use the [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2) workflow to archive PDF into PDF/A format and sign the documents. You can configure digital signatures in the profile configuration of the Archive as PDF/A-2 workflow. ## Features and limitations Compared to the other workflows, this workflow has the following features and limitations: ### Sign only In the Sign PDF workflow it's mandatory to configure digital signature, otherwise the Conversion Service returns a warning. ### Set metadata The signature is not applied on the PDF metadata section so you can add a new signature while changing the metadata of the document. **note: In an appropriate PDF reader you can see the previous signed version with the original metadata.** ## Events The Sign PDF workflow can generate the following events during processing. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `SignatureRemoved` | Removed cryptographic signatures. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the Sign PDF workflow The Sign PDF workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Any subsequent jobs processed with the workflow profile use the profile's default settings. | Type | Option | Description | | --- | ---- | --- | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.AUTHOR` | The author of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.TITLE` | The title of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.SUBJECT` | The subject of the document | | **[Metadata](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata)** | `META.KEYWORDS` | Keywords that apply to the document | **note: You can also set [extended metadata properties](https://www.pdf-tools.com/docs/conversion-service/workflows/metadata#extended-properties) apart from the standard metadata properties.** ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## Stamp and annotation Stamping and annotations add small bits of content to the existing content of PDF pages. A stamp is a fixed visual mark placed on a page, whereas an annotation is an interactive element that lets users to move, resize, or remove the annotations if they are allowed to edit the resulting document in their PDF viewer. In the Conversion Service Configurator, you can configure the following types of **stamps and annotations**: - Text - Image - Barcode **info: Add and configure stamps and annotations within a workflow by enabling **Stamp and Annotation** toggle in a specific profile configuration. For more details and procedures, review **[Configure stamping](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping)**.** ## Workflow specific settings Some workflows have special configuration settings for stamping. For example, you can configure the exact page on which you want to apply the stamp. - For [Archive as PDF/A-1](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_1), [Archive as PDF/A-2](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_2), [Archive as PDF/A-3](https://www.pdf-tools.com/docs/conversion-service/workflows/pdfa_3) and [Convert to PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion) workflows, you can select the page where the stamp or annotation will be applied. There are three options: - **All**: The stamp is applied to all pages of all documents. - **First**: The stamp is applied to the first page of the main output document. An error is triggered if the resulting document is a collection. - **Last**: The stamp is applied to the last page of the main output document. An error is triggered if the output document is a collection. - In the [Create Dossier PDF](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier) workflow, you can choose to apply stamps to the table of contents pages. --- ## Archive as TIFF workflow :::info[Workflow identifier] This workflow is identified as **Archive TIFF** in the Conversion Service. Learn how to automatically convert documents, images, and office files to TIFF format suitable for archiving using the Archive as TIFF workflow in the Conversion Service. The Archive as TIFF workflow is engineered specifically to prepare documents for archiving. The Archive as TIFF workflow supports the following features: - Single-page or multipage TIFF output - Office conversion (optional) - Stamping (optional) ## Supported file formats for Archive as TIFF workflow The Archive as TIFF workflow supports the following file formats: | Content type | File type | |------------------|--------------------------------------------------------------------------------------| | PDF formats | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | | Image formats | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP, JFIF | | Email | EML, MSG (without encryption) | | Word | DOC, DOT, DOCX, DOCM, DOTX, DOTM, RTF, XML (WordprocessingML 2003) | | Excel | XLS, XLT, XLSX, XLSM, XLTX, XLTM, XML (SpreadsheetML 2003) | | PowerPoint | PPT, PPS, PPTX, PPTM, PPSX, PPSM | | OpenOffice | ODT, ODS, ODP | | Other | CSV, HTML, HTM (prepared for archiving), TXT, XML, ZIP (without password protection) | :::caution[Note on OpenOffice formats] PDF conversion of OpenDocument Format depends on the rendering in Microsoft Word, Excel, or PowerPoint. In particular, the conversion can result in visual differences in tables and tabs. The visual differences caused by the difference in rendering of shapes are usually not acceptable. :::caution[Note on HTML format] HTML documents need to be self-contained (layout information and images are either inline or available on the web) and suited for portrait page layout. JavaScript content is disabled during processing. :::caution[Note on XML format] Make the layout information and images defined as links in the XML files available on the web to incorporate them into the TIFF output. The conversion of most file formats is enabled by default in the profile's Convert mode for child documents (attachments). ## Features and limitations Compared to the other workflows, this workflow has the following features and limitations: ### Multi or single-page conversion TIFF format supports multiple pages in one file. You can configure the multipage output for each individual input document using the `MULTIPAGE` option. When you disable the multipage option, the output is one file for each page of the input document. ### Compression The TIFF workflow supports multiple different compression types. You can set the compression type of and quality depending on the input image type. ### Collect mode The TIFF standard does not allow embedded files. Therefore, **Merge** is the only collect mode configuration available. ## Events The Archive as TIFF workflow can generate the following events during processing. For detailed descriptions of each event code, refer to [Events reference](https://www.pdf-tools.com/docs/conversion-service/workflows/events). | Code | Description | | --- | --- | | `CorruptionRepaired` | Corrupt document repaired automatically. | | `ContentRecovered` | Parts of a corrupt document's content recovered. | | `ExternalResourceUnavailable` | External resource couldn't be reached. | | `VisualDifferences` | Conversion resulted in visual differences. | | `SignatureRemoved` | Removed cryptographic signatures. | To configure how events are handled, refer to [Configure event behavior](https://www.pdf-tools.com/docs/conversion-service/workflows/events#configure-event-behavior). ## Job and document options for the TIFF workflow The TIFF workflow lets you use [job and document options](https://www.pdf-tools.com/docs/conversion-service/configure/configure-job-and-document-options) to pass job and document-specific values to be used when processing documents using the workflow. **note: Job and document options you pass at runtime affect only the current job. When you change a setting of the job or document options, that change applies only to the current job. For the next job, the workflow reverts to the profile settings (saved default) unless you pass job or document options again.** ### Job options Job options apply to all documents processed in the same job. Use the default profile settings for any subsequent jobs processed with the workflow profile. | Type | Option | Description | | --- | ---- | --- | | [Multi or single page output](#multi-or-single-page-conversion) | `MULTIPAGE` | Turn on or off multipage output. If `true`, documents included in the job are outputted as a single file with multiple pages. If `false`, documents included in the job are outputted as single-page files. | | [Compression](#compression) | `QUALITY` | The compression quality is applied for each of the compression types. | ### Document options Document options apply only to a specific input. It allows you to determine specific properties based on an individual document, rather than as a global setting (determined by the job or the profile). Use the default profile settings for any subsequent jobs processed with the workflow profile. | Type | Option | Description | | --- | ---- | --- | | Document property | `DOC.PASSWORD` | Set the password for the document. | --- ## PDF information Learn about PDF standards, specifications, and digital signature fundamentals. --- ## Digital signature basics Learn about digital signatures, differences between electronic and digital signatures, public key infrastructure, certificate authorities, and electronic signature laws and regulations. **tip: Pdftools software that lets you manage digital signatures:** - The [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/). Review [Configure signature](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/). - The [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/). Review [Sign PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/). ## The purpose of digital signatures A digital signature can satisfy the legal requirements of a handwritten signature but also offers significant time and resource savings. When comparing digital signatures to handwritten signatures, we can mention the following benefits: - Physical presence of the signatory is not required. - Postage prices for signing many documents with signers in different locations can be high. - There is no need to print documents only to sign them. **note: In some legal cases, the signature is not binding, and an additional physical signature on paper is required.** Applying an electronic signature is very similar to a handwritten signature: A person reads a document and signs it with its name. A valid electronic signature is a section of data embedded in the document. You can use this signature to: - Ensure the document's integrity and that it wasn't tampered with. - Authenticate the signer of the document. - Prove the file has existed before the date. ## Difference between electronic signature and digital signature You may have noticed that the terms **electronic signature** and **digital signature** are often used interchangeably. Still, these terms carry different meanings. Electronic signature is a general umbrella term for various types of signatures. Digital signature is a subtype of electronic signatures with specific technical improvements and agreed legal requirements they meet compared to electronic signatures. In short, all digital signatures are electronic signatures, but not all electronic signatures are digital signatures. **info: While all digital signatures are electronic signatures, not all electronic signatures are digital signatures.** Note that these terms can have **country-specific differences** in translation, interpretation, and legal acceptance. ### Electronic signature In general, an electronic signature is data in electronic form attached to other electronic data in a document. In its simplest form, an electronic signature can be an image of your signature that you include in a document (for example, PDF, RTF, DOC, DOCX). Even your email signature is an electronic signature. ### Digital signature A digital signature is created by applying a **cryptographic algorithm** to the document, which provides additional security. This cryptographic algorithm requires personal information (your **private key**). This information relies on an advanced **Public Key Infrastructure (PKI)** method. Cryptographic signatures follow strict regulations such as the **European Union eIDAS** or **Swiss ZertES**, providing a trusted, secure, and auditable signature. ## Public key infrastructure Public key infrastructure is a framework for securing communication over the internet. It verifies the identity of parties involved in a transaction and encrypts or decrypts the data exchanged between them. Two keys are necessary to verify, encrypt, and decrypt the data: - **Public key** - **Private key** Both keys are explained in the following sections. ### Public key The public key is a large numerical value used to encrypt data and is **part of your certificate**. Your certificate is a file with an extension such as `.cer,` `.pem`, or `.crt` that stores information about the owner and contains the public key. **note: This file format cannot store private keys and can store only one certificate, [X.509](https://en.wikipedia.org/wiki/X.509) (the standard defining the context and layout of public key certificates).** **tip: Your public key information is not sensitive; you can share it with others.** ### Private key The private key is a large numerical value used in an encryption algorithm to decrypt data. It is **part of your Digital ID**, which could have different representations. You can store it in a physical smart card, an HSM device, or a file on your disk. **info: In the case of smart card authentication, your user credentials, which are your public and private keys and certificate, are stored on a smart card. You are authenticated when you insert a card into a card reader and then provide a PIN.** **Smart card example** Smart card example 1. Ryan has a smart card containing a private key. Ryan signs a document with the smart card and then sends the document to Julia. The private key is kept secret and remains with Ryan because, as the smart card owner, only he can sign the document with that private key. 2. Along with the document, Ryan can create a certificate containing the public key they make available to Julia. You can share the certificate safely with anyone, as it only contains the means to validate a signed document. 3. When Ryan publicly shares their certificate, Julia receives the document and can verify that Ryan, the private key owner, signed it. Julia can be sure that nobody modified the document since Ryan signed it. The certificate contains information about the signee. It states who owns the private key that belongs to that certificate. ### Digital ID A digital ID is a file that proves your identity details, similar to a driver's license or a passport. Digital ID contains **two important sections** - Your **private key** to decrypt data. - When you sign PDFs, you use the private key to apply your digital signature. - Your **certificate contains your public key** to encrypt data. - You can distribute the certificate to those who want to validate your signature or identity. :::tip[Store your digital ID in a safe place] Your digital ID contains your private key, which others can use to sign in your name. **note: Digital ID files, also called **PKCS#12** files, have the **.pfx** (Windows) or **.p12** (macOS) extensions.** They can be used interchangeably between operating systems. This archive file format stores many cryptographic objects in a single file. ### Chain of trust (certification path) The chain of trust refers to your certificate and its link to a trusted **certificate authority (CA)**. Certificates (or signatures) can be verified based on other certificates. We can trace back the verification to the public keys of root authentication providers, showing that many people know and accept these keys. CAs operate on a hierarchical basis. At the top of this hierarchy are the Root Certificate Authorities (Root CAs), responsible for verifying and issuing certificates to subordinate certificate authorities. These Root CAs are trusted entities worldwide and form the foundation of the public key infrastructure. The **trust chain**, which includes all issuer certificates and the root certificate, must be embedded in the digital signature. The trust chain ensures that the signature can be verified by any party that trusts the Root CA. Embedding the trust chain in the signature requires all issuer certificates, including the root certificate. ## Certificate authorities A certification authority (CA) is an entity that stores, signs, and issues digital certificates (digital IDs) that certify the ownership of a public key. For more details, review the previous section [Chain of trust (certification path)](#chain-of-trust-certification-path). :::info[Important] A digital signature or digital ID is commonly known as a **digital certificate.** **note: It's important to **distinguish between X.509 certificate files** in `.cer` or `.crt` format **and combined certificates that contain private keys** in `.p12` or `.pfx` format.** ### Verify the signee In X.509 certificates, the certificate path describes a third party, known as a certification authority, which verifies the validity of the information in the certificate connected to a specific person. Certification authorities are responsible for checking the identity of the person who requests a certificate. If a **trusted CA** issued a certificate, you can trust it also. ### Trusted certificate authorities There are two primary sources for verifying whether a trusted CA issued the certificate. If the Root certificate is trusted, you can trust the certificate. #### The Adobe Approved Trust List (AATL) You can trust that the [listed CAs and Trust Service Providers (TSPs)](https://helpx.adobe.com/acrobat/kb/approved-trust-list1.html) comply with global legal and regulatory requirements, including the EU eIDAS regulation. You can also find Digital ID providers that are approved outside of the EU. #### European Union Trusted Lists (EUTL) The [European Union Trust Lists are public lists](https://helpx.adobe.com/document-cloud/kb/european-union-trust-lists.html) containing more than 200 active and former trust service providers (TSPs) who, according to their accreditation, best meet the eIDAS electronic signature regulation requirements. Once you get your digital ID from one of the providers below, securely signing documents becomes easy. ### Private certificate authorities With a Windows Server, you can create a CA to manage issued and pending certificates through a web interface. This is a fine solution for internal usage. You can access your Certificate Services through Active Directory. In the following picture, **PDF Tools RootCA2** is the private CA, and **PDF Tools Support** is the certificate issued. If you share your signed PDF with a third party that doesn't have the certificates installed on their local machine, they are prompted with warnings at the signature panel and the certificate properties. If you trust this person, there are two ways to accept their certificate: - Add the certificate through the Adobe Acrobat Reader interface. - Add it manually to your Windows Certificate Store. ### Self-signed certificate A root CA is not always necessary. You can create a custom digital ID and sign documents with a self-signed certificate. The following sections, [Create digital ID with Adobe Reader](#create-digital-id-with-adobe-reader) and [Create digital ID with PowerShell](#create-digital-id-with-powershell) explain two ways to create a self-signed certificate. #### Create digital ID with Adobe Reader You can follow the steps in [Create a self-signed digital ID](https://helpx.adobe.com/acrobat/using/digital-ids.html#create_a_self_signed_digital_id) in Adobe documentation. By the end of this process, you will create a `.pfx` file. This file contains the private key and the X.509 certificate (which includes the public key). #### Create digital ID with PowerShell 1. Create a certificate and install it on your local machine (Personal Certificate Store): ```powershell New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "TestCert" ``` 2. Secure your certificate: ```powershell $pwd = ConvertTo-SecureString -String "Password" -Force -AsPlainText ``` 3. Export the certificate with a password: ```powershell Export-PfxCertificate -cert cert:\localMachine\my\5663345E048BFD700866449B286F777DAB8D3C12 -FilePath root-authority.pfx -Password $pwd ``` - Replace the example thumbprint `5663345E048BFD700866449B286F777DAB8D3C12` with the one you generated. :::info[Important!] In the Conversion Service, you can't use the `.pfx` file directly, but you can install it to the Windows certificate store under the user who runs the application, which is the SYSTEM user. ### Certificate revocation information You can revoke your digital certificate when you lose it. As a result, anyone who finds or acquires your original certificate cannot use it to sign on your behalf illegally. In this case, it's getting invalidated before the expiry date. All the signatures you created before that time remain valid, but the ones you created later will be invalid. The signature ensures that the certificate was valid when the document was signed (due to the embedding of the OCSP/CRL response). #### Online certificate status protocol (OCSP) [OCSP](https://datatracker.ietf.org/doc/html/rfc2560) is a protocol for interactively checking the revocation of a single certificate. It can provide more timely revocation information than CRLs. #### Certificate revocation list (CRL) A [CRL](https://datatracker.ietf.org/doc/html/rfc3280) is a list of digital certificates the CA revoked before their scheduled expiration date. The CRL is an online service where you can check if a certificate is valid. ## Electronic signature laws and regulations (EU) The strength and reliability of the signature you want to use are tied to your requirements. CA's responsibility is to provide the desired level of strength and reliability. ### Simple electronic signature Simple electronic signatures have no legal significance. A simple electronic signature can be a cryptographic signature. A cryptographic signature is generated using a digital certificate, but the certificate is not from a trusted Certificate Authority. It can be a self-signed certificate, which means it doesn't have an issuer or can be created by some private CA like a company (for example Pdftools) that issues a new certificate. A simple electronic signature cannot verify the identity of the signer. Using a simple electronic signature brings the following advantages: - The signature ensures the integrity of the signed content. - Subsequent changes in the data are detectable. ### Advanced electronic signature (AdES) Legally, the advanced electronic signature is similar to a company stamp. It's used for mass signature. **note: While legally binding in many contexts, AdES is not identical in its legal status or formal recognition to an official handwritten signature.** A trust service provider or CA (such as SwissSign) issues digital certificates for AdES e-signature type, typically after verifying an individual's identity. Certificates in this category meet the requirements of **eIDAS**, which means they are regulated by law and have strict processes. **tip: To receive an advanced certificate, the owner must prove their identity, for example, by physically visiting the CA and presenting their passport.** The owner can be a legal person or entity. An advanced certificate contains the owner's name, the name of the CA, the period of validity, and other information. The AdEs brings the following advantages over a simple electronic signature: - Capable of identifying the signatory, who can be a legal person or an entity provided by a trusted CA. - You can acquire Certificate revocation information from an online service. Embed the valid response (for example: valid, revoked) in the signature (OCSP, CLR). - Protected private key storage. #### OCSP and CRL Embedding revocation information is optional but recommended when applying advanced (AES) or qualified electronic signatures (QES). The signing certificate includes the revocation information and all certificates of its trust chain. Therefore, the same message may present both OCSP responses and CRLs. However, embedding revocation information increases the file size (usually around 20 kB) and requires an external request to a validation service, which may delay the signing process. ### Qualified electronic signature (QES) The requirements for a **qualified certificate** and qualified signatures vary by country. You can't make mass signatures with them. **info: In many European Countries, a qualified electronic signature (QES) is equivalent to a handwritten signature.** Nobody can sign the document without the user's interaction. As a result, the QES is equal to a handwritten signature, meaning that you can apply only one signature at a time. :::info[Examples] The QES is a signature created by a qualified electronic signature creation device (QESCD). For example, a physical smartcard held by the signer with an associated PIN code or hardware security module operated remotely by a qualified trust service provider (QTSP) in the cloud. You have to enter the PIN code manually. This signature can also be approved from a mobile phone. A qualified electronic signature is similar to an [advanced electronic signature](#advanced-electronic-signature-ades) but has higher requirements. The main differences are: - The key storage must ensure that the user approves the signature manually when you sign the document. - A time-stamp can be required to ensure the integrity of the signing time. - Supports QES useful for legal processes. #### Qualified certificate Qualified certificates for electronic signatures issued by a Qualified Trust Service Provider (QTSP). A QES based on a qualified certificate issued in one EU Member State is recognized in all other EU Member States. #### TSP and QTSP Generally, there are two types of trust services: - Trust Service Provider (TSP) - Qualified Trust Service Provider (QTSP) Only a QTSP can provide a qualified version of the services, which can be described as additional security. ## Types of electronic signatures There are different types of electronic signatures that Pdftools provides. ### Document signature The most usual type of signature is a document signature, also called an approval signature. You need a digital certificate to create this type of signature. The main responsibilities are: - Ensure the integrity of the document. - Authenticate the signer's identity. **note: You can modify and save signed documents by incremental updates. The document's state can be recreated as it existed at the time of signing.** Optional responsibilities: - Optional visual appearance in the document. - Optional time-stamp provided by a time-stamp authority (TSA). - Optional long-term validation (OCSP, CRL). - You can add multiple signatures. #### Multiple signatures in archived documents Many types of documents that require digital signatures also require archiving. PDF/A conformance is often necessary for archiving to ensure the file is not corrupt and its visual appearance is well-defined and reproducible. However, during the conversion process from PDF to PDF/A, signatures could be removed from the file before it is converted to PDF/A for archival. Even if your PDF is archived, the signature can be removed if it doesn't conform to the best possible conformance level. Before any digital signatures are applied, archive the files in PDF/A format. **info: When you archive files in the Conversion Service using the Archive PDF/A workflow, the service first removes the previously applied digital signatures before archiving a file.** :::tip[Suggestion] Signature workflow lets you add additional signatures to your archived PDF, even if it doesn't conform to the best possible conformance level. ### Document certification signature **note: You can't add this type of signature to your document with the Conversion Service. However, leverage the document certification signature with the Pdftools SDK.** It's also called the Modification Detection and Prevention signature (MDP). A document can contain only one MDP signature, which must be the first. Other signature types can be present. The document certification signature is similar to the [document signature](#document-signature), but the author can define what changes they allow and which modifications they prevent. The main differences are: - Document certification signature detects changes. - Displayed differently in Adobe Reader. - You can add only one MDP signature. - It's to contain a signature visual appearance, time-stamp, or long-term validation. ### Document time-stamp signature A time-stamp signature proves that the document existed at a specific time and protects its integrity. You can apply one or more Document Time-stamp signatures. A signed document can be modified and saved incrementally. **info: You can use time-stamp signatures separately, but including a time-stamp signature in document signatures is common.** Main responsibilities: - It's a simple signature that ensures the integrity of the document. In Adobe Reader, it's displayed as a watch symbol. - It's a Proof of Existence (PoE). #### Time-stamp authorities A time-stamp authority (TSA) provides trusted, cryptographically secure time-stamp information. This time-stamp information can be used to apply a digital time-stamp to a document, which verifies that the document existed at a point in time and that its content wasn't changed. A time-stamp signature does not require a local signing certificate. Instead, the time-stamp signature requested from the time-stamp authority is embedded into the document. However, a cryptographic provider that supports time-stamp signatures is required. ### Unsigned signature field **note: You can't add this type of signature to your document with the Conversion Service, but you can leverage it with the Pdftools SDK.** You can set a position where you expect to have a signature. ## PaDES Standard - PDF Advanced Electronic Signatures PAdES is a technical standard for PDF documents and refers specifically to restrictions and extensions of electronic signatures. With PAdES, you can provide a unique electronic signature. **note: The 'advanced' part of the name refers to the upgraded security and validation methods it provides for electronic document signatures.** Don't confuse the 'advanced' with the 'advanced' part in the AdES signatures. #### History of PaDES - Before this standard, signatures varied and were incompatible across different software. - The European Telecommunications Standards Institute (ETSI) published the PaDES technical standard in 2009, which makes signatures interoperable between different software. - The PaDES was updated in 2011 and later in 2015 to the European norm ETSI EN 319 142. The update provided an improved specification that is still widely accepted. **note: Signatures that you can create with the Conversion Service provide compatible standards.** The following table informs about the historical evolution of the names of these standards. The first column is the latest standard defined in the ETSI EN 319 142 norm with four baseline signature levels recommended by the PAdES European standard. The second, third, and fourth columns display previously defined standards. Although the names differ based on the standards, they have similar meanings but also some slight differences: | ETSI EN 319 142 | ETSI TS 102 778 | ETSI TS 103 172 | ISO 14533-3 | |-----------------------------------|-----------------|-----------------|--------------| | **[PAdES B-B](#pades-b-b)** | PAdES-BES | PAdES B-Level | - | | **[PAdES B-T](#pades-b-t)** | PAdES-BES | PAdES T-Level | PAdES-T | | **[PAdES B-LT](#pades-b-lt)** | PAdES-BES | PAdES LT-Level | PAdES-A | | **[PAdES B-LTA](#pades-b-lta)** | PAdES-LTV | PAdES LTA-Level | PAdES-A | ### PAdES B-B PAdES B-B is a basic digital signature that contains information about the document's integrity and the signee's authenticity. ### PAdES B-T PAdES B-T is a digital signature with a time-stamp token. ### PAdES B-LT PAdES B-LT is a digital signature with a time-stamp token and long-term validation data. #### Advantages of long-term signature Every signature expires. The period after which signatures expire is usually five years. You cannot see if the certificate was revoked when a signature validity period expired. To solve the problem, you can embed validation data that you can get from your online service. If someone looks at the document after the signature has expired, they can see the validation data to check the certificate was not revoked when the signature was created. If your signature is not long-term, you can only see if it was revoked until it is valid. **info: You can configure the Conversion Service to embed long-term validation (LTV) information into a document during the signing.** This setting attempts to embed revocation information such as OCSP and CRL. A validation service provides the revocation information at the time of signing and acts as proof the certificate was valid at the time of signing. ### PAdES B-LTA PAdES B-LTA is similar to PAdES B-LT but adds a document time-stamp at the end of the document **note: The time-stamp improves the data protection. The original algorithm can become obsolete, and attackers (such as hackers) may abuse your signature.** Included time-stamp can ensure that a specific algorithm needs to be updated. ## Signature validation Validate signatures using sources such as certificates, Online Certificate Status Protocol results, and Certificate Revocation List results. These sources can be embedded in the PDF file, stored on the local machine, or downloaded from the issuer. Three items need to be validated: 1. Trust chain 2. Revocation information (optional) 3. time-stamp (optional) --- ## PDF/A specification PDF/A is an [ISO standard](https://www.pdf-tools.com/docs/knowledge/pdf-standards) for using the PDF format for long-term archiving of electronic documents. ## PDF/A-1 PDF/A-1 (ISO 19005-1) is based on PDF 1.4 (Acrobat 5). In addition to the PDF 1.4 requirements, it specifies that documents must be kept self-contained and suitable for long-term archival. **Key differences between PDF 1.4 and PDF/A-1** - Encryption may not be used. - If device-dependent color space is used (i.e. DeviceRGB, DeviceCMYK, DeviceGray), a corresponding color profile must be embedded. - Fonts used for visible text must be embedded. - Transparency may not be used. ## PDF/A-2 PDF/A-2 is described in ISO 19005-2. It is based on ISO 32000-1, the standard for PDF 1.7. PDF/A-2 is meant as an extension to PDF/A-1. The second part complements the first part and does not replace it. **Key differences between PDF/A-1 and PDF/A-2** - The list of compression types has been extended by JPEG2000. - Transparent contents produced by graphic programs are allowed. - Optional contents (also known as layers) can be made visible or invisible. - Multiple PDF/A files can be bundled in one file (collection, package). - The additional conformity level U (Unicode) allows for creating searchable files without having to fulfill the strict requirements of the conformity level A (accessibility). - File size can be reduced using compressed object and XRef streams. Any documents that contain these features (particularly, layers or transparency) should be converted to PDF/A-2 rather than PDF/A-1. ## PDF/A-3 PDF/A-3 is described in ISO 19005-3. It is based on ISO 32000-1, the standard for PDF 1.7. PDF/A-3 is an extension to PDF/A-2. The third part complements the second part and does not replace it. **Key differences between PDF/A 2 and PDF/A 3** - Files of any format and conformance may be embedded. Embedded files need not be suitable for long-term archiving. - Embed files can be associated with any part of the PDF/A-3 file. --- ## PDF standards PDF (Portable Document Format) is a file format developed to display documents (including text and images). It is designed to be software, hardware, and operating system independent. There are several ISO standards that cover PDF: - [Standard file format](#standard-file-format) - [Specialized uses](#specialized-uses) ## Standard file format Developed by Adobe as a proprietary format ([Adobe PDF 1.0](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.0.pdf)) in 1992, PDF was designed to be a digital form for representing electronic documents. The format enable users to exchange and view electronic documents independent of the environment in which they were created or the environment in which they are viewed or printed. PDF files may contain a variety of content: - flat text - graphics (images) - logical structuring elements such as document outlines (table of contents) - interactive elements such as annotations and form fields - layers - rich media, including video content - three-dimensional objects using U3D or PRC - other data formats The PDF specification also provides for encryption and digital signatures, file attachments, and metadata to enable workflows requiring these features. ### PDF 1.7 (ISO 32000-1) To further increase acceptance of PDF as a format, Adobe Systems submitted [PDF Version 1.7](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf) to the ISO for standardization. On July 1, [2008 ISO 32000-1 Document management — Portable document format - Part 1](https://www.iso.org/standard/51502.html) was published, turning PDF into an ISO standard. The standard governs the software that creates the PDF files (confirming writers), software that reads PDF files and interprets the contents for display and interaction (conforming readers), and PDF products that read and write PDF files (conforming products). ### PDF 2.0 (ISO 32000-2) Part 2 of the standard was put forward and approved by the ISO members. The list of changes contains more than 50 entries that refer to new features, improvements, and the clean-up of legacy issues that were present in the ISO 3200-1 standard. The new part of the standard mainly concerns rendering, transparency, digital signatures, metadata, and accessibility. While this new part based on the preceding part, ISO 3200-1 continues to be current. However, the term conforming reader has been replaced and redefined as interactive PDF processor (software that reads and displays PDF content and interacts with the computer users to possibly modify and save the PDF file), PDF reader (software that reads existing PDF files and interprets their contents for display), and PDF writer (software that creates PDF files). ## Specialized uses There are several technical specifications that determine the use of the PDF file format within specific applications: - [Archiving](#pdfa---archive) - [Exchange](#pdfx---exchange) - [Variable and transactional printing](#pdfx---exchange) - [Universal accessibility](#pdfua---universal-accessibility) - [Engineering](#pdfe---engineering) - [Healthcare](#pdfh---healthcare) ### PDF/A - Archive The PDF/A standard (ISO 19005) defines the specifications for the archiving of digital documents. The PDF/A standard ensures that the visual appearance of electronic documents is preserved over time. This guarantees the readability of PDF/A-compliant documents. There are four versions of this standard. ### PDF/X - Exchange PDF/X (ISO 15930) standardizes PDF as graphics files for printing. Several improvements and changes have been incorporated since it was first drafted in 2001. The current version is PDF/X-5. ### PDF/UA - Universal Accessibility PDF/UA (ISO 14289) aims to make PDF documents accessible to people with disabilities. The standard includes guidelines on how PDF documents and the information elements they contain, such as graphics, text, multimedia elements, and form fields, must be made available so that they can navigate in the document, as well as receive the content via voice output. ### PDF/VT - Variable and transactional printing Printing, packing, and franking transactional documents, whether they are essential business documents such as delivery notices, invoices and payment reminders or direct marketing letters sent out in sheer endless numbers, is a billion dollar market. The high numbers of print jobs and the requirements for short through-put times have not only led to the development of corresponding hardware like high-performance printers. Applications like Variable Data Printing (VDP) have been created in order to significantly cut the cost per printed item. These facts and the huge demand for a universal and standardized VDP solution have led to the development of PDF/VT. ### PDF/E - Engineering PDF/E is a standard for technical documents in engineering, architecture and geo-information. The depiction of 3D objects and the exchange of plans/drawings shall be covered by the PDF/A-4e standard in the future. ### PDF/H - Healthcare PDF/H is a guideline to regulate the creation, exchange, retention, and protection of healthcare-relevant information. PDF/H aims to close the gap between healthcare institutions and the consumer. --- ## Licenses of Pdftools products A valid license key is required to use the Pdftools products without limitations. Some products allow you to try them without a license key with watermarked results. See the list below for more details: - **Pdftools SDK**: Watermarked results without a valid license key. Use a valid license key to remove the watermark. - **Toolbox add-on**: Use a valid license key to try or work with the product. - **Conversion Service**: Use a valid license key to try or work with the product. - **PDF Viewer SDK**: Watermarked results without a valid license key. Use a valid license key to remove the watermark. - **AI Smart Redact**: Use a valid license key to try or work with the product. Other shell tools and SDKs: - **PDF Toolbox SDK**: Use a valid license key to try or work with the product. - **3-Heights SDK**: Use a valid license key to try or work with the product. **info: Do you need a full product license, a new license key, or an upgrade to your current license, or do you want to ask us anything else? Get in touch with our team through the [Contact page](https://www.pdf-tools.com/contact/).** ## Identifying a license key This section helps you identify the product for which a specific license key can be used. To identify the product, compare your license key with the following examples: **Pdftools SDK:** ``` ``` **info: - Value `PDFSDK` indicates that the license key belongs to Pdftools SDK.** - Values such as `V1` and `V4` change depending on the release version. - To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key. **Conversion Service:** ``` 4H-V6-JV0VY-GYQT3-4O73M-4CCWO-LXK0T-3J741-5TKUA ``` **info: - The Conversion Service license key includes seven times five strings of alphanumeric characters (after `4H` and `V4` in the example above).** - Values such as `V1` and `V4` change depending on the release version. **PDF Viewer SDK:** ### Version 5 ``` ``` **info: - Value `VIEWWEB` indicates that the license key belongs to the PDF Viewer SDK.** - Values such as `V1` and `V5` change depending on the release version. - To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key. ### Version 4 ``` <4H,V4,VIEWWEB,A93H49S73H3QQSW99SFIR5V78NHVZS49BT3I6MD4L> ``` **info: - Value `VIEWWEB` indicates that the license key belongs to the PDF Viewer SDK.** - Values such as `V1` and `V4` change depending on the release version. - To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key. **PDF Toolbox SDK:** ``` <4H,V4,TOOLSDK,LGKI1RJLSZUCXPFW4ETHG06N4> ``` **info: - Value `TOOLSDK` indicates that the license key belongs to the PDF Toolbox SDK.** - Values such as `V1` and `V4` change depending on the release version. - To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key. **3-Heights SDK:** ``` 1-5IAXL-C3SJE-040YC-52T0J-CH98P-7KCY7-WLNF0 ``` ``` 0-DHT83-AF2V1-31OG8-5U7FA-KXNBF-YQKS9 ``` **AI Smart Redact:** ``` ``` **info: - Value `RDCTSRV` indicates that the license key belongs to AI Smart Redact.** - Values such as `V1` change depending on the release version. - To correctly validate the license key, include the angle brackets (`<>`) at the beginning and the end of the license key. ### License key activation The process of activating and using a license key varies depending on the Pdftools product or version. See the respective product pages for detailed license information: - [Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license) - [Toolbox add-on](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license) - [Conversion Service license](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license) - [Pdftools OCR Service](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license) - [PDF Viewer SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-web-viewer-license) - [PDF Toolbox SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-toolbox-sdk-license) - [3-Heights SDK licenses](https://www.pdf-tools.com/docs/licenses/products/3-heights-licenses) - [AI Smart Redact license](https://www.pdf-tools.com/docs/licenses/products/smart-redact-license) ## Frequently asked questions Questions commonly asked about licenses: **Error activating license (...) License already activated 1 times** Check that you haven't activated the license already on another machine. If so, deactivate the license on that machine. To deactivate a license, see [Deactivation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=11) section in Technical Note: License Keys. If the error persists, open a support request: 1. Sign up or log in to [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the [Support](https://portal.pdf-tools.com/support) page. 1. Click **Open a support request**. 1. Fill in any necessary information, and then click **Submit**. **The license added in the License Manager stops working. A red cross appears and the software doesn't work.** Some Pdftools licenses need to be activated. The license works for approximately 10 days without activation. The date after which it requires activation is displayed in the License Manager in "Activation necessary starting...". To activate a Pdftools license for PDF Toolbox SDK and PDF Viewer SDK, see [License activation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=10). To activate a 3-Heights product license, see [License activation](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys3Heights.pdf#page=10). **Error connecting to the licensing server** **Pdftools SDK** Check your network connection. If the SDK is unable to connect to the licensing server, the license (and the product usage) is blocked. To be able to activate licenses and use the product offline, you must have set up the [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/). **PDF Toolbox and PDF Viewer SDK** If the License Manager is unable to connect to the Licensing server, you can update, activate and deactivate the license offline. See [Offline usage](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=11). If you use a proxy server, ensure that the proxy allows connections via HTTP CONNECT to `license.pdf-tools.com:443` and add the license server URL to an allow list in your firewall. **The licensing server returned an error: 301 Moved Permanently** You are using an old version of the License Manager (older than 4.11.18.0), which doesn't use HTTPS. Update to the latest version of the License Manager and try to deactivate, activate, and update the license again. **Error updating the license key in the License Manager** Check that: - The license key is still active for the product and hasn't expired. Evaluation licenses expire after 30 days. - The format of the license key is correct for the product. See [Identifying a license key](#identifying-a-license-key) section. - The license hasn't been installed on another machine. Otherwise, you need to deactivate the key on another machine before you can add it to the new machine. - The license hasn't already been installed on a machine. An **Error storing key: File exists** message appears. **Error storing key: The license key has been manipulated** 1. A typographical error in the license key. Try typing the key again. Make sure no blanks are added when copying the key. 2. Example key (1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX) is used. The X character represents a numerical value and is not an active license key. 3. Download the key from the [Pdftools Portal](https://portal.pdf-tools.com/) and add/store it on the machine. **LIC_E_FEATURE error: The use of this function requires additional features activated in the license key** Some Pdftools products include optional features that require activation in the license key. If you receive this error, contact [Pdftools Sales](https://www.pdf-tools.com/contact/) to request the feature. **SSL certificate problem: unable to get local issuer certificate** Older systems may not trust the Amazon root certificate **Amazon Root CA 1**, potentially causing issues. Follow these steps to resolve them: 1. Download the root certificate [Amazon Root CA 1](https://www.amazontrust.com/repository/AmazonRootCA1.pem) from the Amazon website. 2. Add it to your system's trusted root certificate store. --- ## Pdftools Licensing Service Learn about the available configuration options for managing the Pdftools license keys. This page provides a basic overview of the licensing system and links to relevant documents that guide you through installation and configuration. A valid license key is necessary to use the Pdftools products. A cloud-based **Pdftools Licensing Service (PLS)** manages the license key validation. You can also use a **Licensing Gateway Service (LGS)** that sends the validation data to the PLS. An internet connection is necessary to validate the license keys in the LGS default configuration. You can configure offline license key validation, where the license keys stay valid without an internet connection for various periods of time. **info: The PLS is available for:** - Pdftools SDK - Conversion Service (version 4.7+) ## LGS supported operating systems and environments The Licensing Gateway Service (LGS) is available for multiple operating systems: | Operating system | Package | Supported architecture | Tested | |-------------------------------------------------|---------|------------------------|------------------------------------------------------------| | Windows 8+ | MSI | x64 | Windows 8, 8.1, 10, 11 | | Linux | Snap | x64 | Ubuntu 22.04+, Debian 12+, Fedora 38+, openSUSE Leap 15.5+ | | Other Linux distribution (glibc 2.34+ and Snap) | Snap | x64 | | :::note[Use MSI instead of Snap on WSL] LGS isn't supported on Windows Subsystem for Linux (WSL). Use the native Windows MSI package instead of Snap on WSL. ## LGS system requiremetns | **Requirement** | **Docker Container** | **Windows** | **Linux** | |-------------------|------------------------------|-----------------------|--------------------------------| | **CPU** | 1 vCPU | 64-bit processor with SLAT support | 64-bit processor with virtualization support | | **Memory** | Minimum of 512 MB | Minimum of 4 GB (recommended 8 GB or more) | Minimum of 4 GB (recommended 8 GB or more) | | **Disk space** | Approximately 300 MB or more | At least 10 GB of free disk space | At least 10 GB of free disk space | ## License validation modes You can set up the Pdftools products in several ways to validate the license keys. The LGS is an intermediary between your local installations of Pdftools products and the Pdftools Licensing Server (PLS). The LGS can borrow license keys for products installed in your network. As a result, machines with Pdftools products don't require an internet connection to validate their license keys. On this page, you can learn about: - The default configuration. Review [Direct connection to the PLS](#direct-connection-to-the-pls) section. - How to enable a partially offline license key validation using the connected mode. Review [Partial or full offline license key validation](#partial-or-full-offline-license-key-validation) section. - How to enable fully offline license key validation. Review [Partial or full offline license key validation](#partial-or-full-offline-license-key-validation) section. ### Direct connection to the PLS In the default configuration, the Pdftools software validates the license keys directly with the PLS. This setup requires a continuous internet connection. Any network outages may disrupt system operations and limit access and usability of the Pdftools products due to connectivity issues. ### Partial or full offline license key validation You can configure the LGS to validate the license keys offline for varied periods of time. - **Connected mode (partially offline configuration)**: Validate the license keys for one or many installations of the Pdftools products in your local network. Your local network can stay without an internet connection, and the license keys are validated from one computer, which serves as the gateway. This computer is the only machine in your network that needs to be online to send the usage data. The computer with the gateway can also stay offline for varied amounts of time. - **Full offline mode**: Stay fully offline with valid license keys for at least three months or more, depending on the type of your license. This option has the same benefits as the **connected mode** and lets the computer with the LGS stay fully offline. #### Connected mode example use cases The Licensing Gateway Service (LGS) is an intermediary between your local installations of Pdftools software and the Pdftools Licensing Server (PLS). The LGS lets you work offline with a valid license key without a network connection. In the connected mode, you only need an occasional internet connection to validate the license key. The following image illustrates the described configuration: Manage license keys in your local network with one LGS. A single LGS enables you to use Pdftools software across multiple machines. One machine with LGS can occasionally connect to the internet to keep your license key valid, while the rest of the Pdftools software installed in your local network can stay offline. The following image illustrates the described configuration: To configure the connected mode, review [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service) page. #### Full offline mode example use case Stay fully offline with your whole system. No internet connection is necessary. You only need to send a license activation token once per three months or more from another machine. This machine can be disconnected from your local network where you work with the Pdftools software. The following image illustrates the described configuration with a fully offline private network: To configure the full offline mode, review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service) page. --- ## Containerized mode Use a Docker image to run the Licensing Gateway Service (LGS) in a containerized environment. This setup lets you run the LGS in a Docker container with internet access, introducing [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service) to Docker containers. For fully offline deployments, review [Full offline mode in Docker](#full-offline-mode-in-docker). :::info[Conversion Service in Docker] If you use the Conversion Service in Docker, use the example file provided in [Configure containers using Docker compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose) documentation to set up containerized mode. :::note[Pdftools OCR Service] The [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) isn't supported in Docker environments, which also means you can't use it with the containerized mode. ## Run the LGS in Docker ### Prerequisites - Install Docker or Docker Compose on the machine intended for the LGS. For more details, review [Docker documentation](https://docs.docker.com/get-started/get-docker/). - The Linux host operating system of the Docker container requires **glibc 2.34+**. ### Run the Docker container To run the LGS in a Docker container: 1. Find the official Pdftools LGS Docker image in the Docker Hub: [`pdftoolsag/license-gateway`](https://hub.docker.com/r/pdftoolsag/license-gateway) 1. Start the LGS container with the necessary configurations: ```bash docker run -p 9999:9999 \ -e LICENSE_KEYS="YOUR_LICENSE_KEY" \ pdftoolsag/license-gateway:latest ``` Replace `YOUR_LICENSE_KEY` with your actual license key. Separate multiple keys with a semicolon (`;`): ```bash -e LICENSE_KEYS="LICENSE_KEY_1;LICENSE_KEY_2" ``` **note: This container requires an active internet connection to synchronize license data. During shutdown, an internet connection is also required to prevent data inconsistencies and blocked licenses.** #### Port mapping By default, the LGS runs on port `9999`. - Port mapping, default set to: **`-p 9999:9999`** - This configuration maps the LGS internal API port to port `9999` on the host machine. - To change the host port, update the configuration in the product or command-line tool accordingly. ## Docker Compose If you prefer to use Docker Compose, create a `docker-compose.yml` file with the following content: ```yaml services: license-gateway: image: pdftoolsag/license-gateway:latest ports: - "9999:9999" environment: - LICENSE_KEYS=YOUR_LICENSE_KEY ``` You can also use multiple license keys separated by a semicolon (`;`): ```yaml services: license-gateway: image: pdftoolsag/license-gateway:latest ports: - "9999:9999" environment: - LICENSE_KEYS=LICENSE_KEY_1;LICENSE_KEY_2 ``` ## Configure a forward proxy If the LGS container connects to the Pdftools Licensing Server through a forward proxy, pass the proxy configuration as environment variables. For a description of each property, review [Configure a forward proxy](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service#configure-a-forward-proxy) in the connected mode documentation. To configure a forward proxy with `docker run`: ```bash docker run -p 9999:9999 \ -e LICENSE_KEYS="YOUR_LICENSE_KEY" \ -e FORWARDPROXY__ADDRESS="PROXY_ADDRESS" \ -e FORWARDPROXY__USERNAME="PROXY_USERNAME" \ -e FORWARDPROXY__PASSWORD="PROXY_PASSWORD" \ -e FORWARDPROXY__BYPASSONLOCAL="true" \ pdftoolsag/license-gateway:latest ``` Replace the following: - `YOUR_LICENSE_KEY`: Your license key. - `PROXY_ADDRESS`: The forward proxy URL including port, for example `http://proxy.example.com:8080`. - `PROXY_USERNAME`: The username for proxy authentication. Omit this variable for non-authenticated proxies. - `PROXY_PASSWORD`: The password for proxy authentication. Omit this variable for non-authenticated proxies. To configure a forward proxy with Docker Compose, add the environment variables to your `docker-compose.yml` file: ```yaml services: license-gateway: image: pdftoolsag/license-gateway:latest ports: - "9999:9999" environment: - LICENSE_KEYS=YOUR_LICENSE_KEY - FORWARDPROXY__ADDRESS=PROXY_ADDRESS - FORWARDPROXY__USERNAME=PROXY_USERNAME - FORWARDPROXY__PASSWORD=PROXY_PASSWORD - FORWARDPROXY__BYPASSONLOCAL=true ``` For non-authenticated proxies, omit `FORWARDPROXY__USERNAME` and `FORWARDPROXY__PASSWORD` or set them to empty strings. ## Automatic LGS deactivation Each license can have a maximum number of LGS instances connected to it, and certain licenses allow unlimited numbers of LGS instances. When you exceed the maximum number of instances, the license becomes blocked. To prevent the license from being blocked, the LGS automatically deactivates itself from the pool of LGS instances associated with the license key when the Docker container shuts down. Deactivation of the LGS for a given license key occurs automatically when the Docker container shuts down. To ensure this process works correctly, always gracefully shut down the container: ```bash docker stop CONTAINER_ID ``` If the container can't connect to the internet during shutdown, it may fail to transfer data properly, potentially blocking the licenses. In such cases, contact Pdftools support to resolve the issue. ## Full offline mode in Docker Full offline mode lets you run the LGS in Docker containers without an internet connection. Each LGS instance requires its own persistent volume to store licensing data. Define each instance as a separate Docker Compose service rather than using replicas, because replicas share a single volume definition. ### Configure offline LGS containers To set up full offline mode, set the `ISOFFLINEMODE` environment variable to `true` and mount a named volume to `/usr/share/Pdftools/Data` on each LGS container. In offline mode, the `LICENSE_KEYS` environment variable isn't required at container startup. License keys are activated after the containers are running through the [activation procedures](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service#license-key-activation). The following `docker-compose.yml` example configures two offline LGS instances: ```yaml services: lgs-1: image: pdftoolsag/license-gateway:latest ports: - "9991:9999" environment: - ISOFFLINEMODE=true volumes: - lgs-1-data:/usr/share/Pdftools/Data lgs-2: image: pdftoolsag/license-gateway:latest ports: - "9992:9999" environment: - ISOFFLINEMODE=true volumes: - lgs-2-data:/usr/share/Pdftools/Data volumes: lgs-1-data: lgs-2-data: ``` Each service maps a different host port (for example, `9991` and `9992`) to the internal LGS port `9999`. ### Activate and deactivate licenses After the containers are running, activate and deactivate license keys using the same procedures described in the [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service) documentation. To manage multiple LGS instances at once, use the [batch activation and deactivation](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service#batch-activation-across-multiple-lgs-instances) commands. --- ## Connected mode Configure the Pdftools software to validate the license keys partially offline using the connected mode, enabling the system to remain operational without a network connection for varied amount of time. The period in which you can validate the license keys offline differs depending on your license type and agreement with the Pdftools. :::tip[Full offline mode] You can also set up a full offline mode that lets you use Pdftools software offline for at least three months. For more details, review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service). :::info[Conversion Service and LGS] The Conversion Service comes with the Licensing Gateway Service (LGS) preinstalled. You can skip the LGS installation step if you plan to use the LGS provided with the Conversion Service on the same machine. Installing the LGS on such a machine for the second time may render the Conversion Service unusable. **Don't follow this page to set up the LGS with the Conversion Service.** To set up the connected mode in the Conversion Service, review [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license#licensing-gateway-service) in the Conversion Service licensing documentation. ## Install the LGS Install the Licensing Gateway Service (LGS) to enable partially offline configuration, download and install the package on a machine in your network that is connected to the internet. **Windows:** 1. Download the LicensingGatewayService.msi package. 1. Run the installer. The installer also creates a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server. **Linux:** :::info[Prerequisite] On Linux systems, the LGS requires **glibc 2.34+**. 1. Download the licgwy_amd64.snap package. 1. Install the snap package: ```bash snap install licgwy_amd64.snap --classic --dangerous ``` The installer also creates a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server. :::info[Linux CLI naming] On Linux, the `ptl` CLI is part of the `licgwy` snap package. Invoke it as `licgwy.ptl` instead of `ptl`. All CLI examples on this page use `ptl` for brevity. To create a shorter alias, run the following command with elevated privileges: ```bash sudo snap alias licgwy.ptl ptl ``` On Windows, the CLI is always `ptl`. All CLI examples on this page use `ptl` for brevity. ## Configure the LGS To configure the LGS: 1. Find the LGS configuration file `appsettings.json`: **Windows:** For Windows, the file is in the installation folder, for example: ``` C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json ``` **Linux:** For Linux systems the file is in the `$SNAP_DATA` directory, for example: ``` /var/snap/licgwy/current/appsettings.json ``` Example configuration file: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7 } ``` 1. You can configure these options: - **Licensing Service Port number**: Set the port number used by the service. The default value is `9999`. - **Log file path**: Specify the desired path of the log files. - **Log retention**: Define the number of days the log files are kept. 1. Restart the service after modifying the `appsettings.json` file for the changes to take effect. 1. To ensure that the LGS can always connect to the Pdftools Licensing Server, add the service to the allowlist of any configured firewall. **caution: If the machine with the LGS becomes inaccessible, you can borrow a license key on another machine without returning it first.** If you try to borrow the license key more than once in this situation, **the license key is blocked**. You cannot use or return the blocked license key on any other machine. To reset the license key, contact Pdftools support. Review the [Support](https://www.pdf-tools.com/docs/support) page. ## Configure a forward proxy If the LGS connects to the Pdftools Licensing Server through a forward proxy, configure the proxy settings in the `appsettings.json` configuration file. To configure a forward proxy: 1. Find the `appsettings.json` configuration file: **Windows:** For Windows, the file is in the installation folder, for example: ``` C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json ``` **Linux:** For Linux systems, the file is in the `$SNAP_DATA` directory, for example: ``` /var/snap/licgwy/current/appsettings.json ``` 1. Add the `ForwardProxy` section with your proxy details: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7, "ForwardProxy": { "Address": "PROXY_ADDRESS", "Username": "PROXY_USERNAME", "Password": "PROXY_PASSWORD", "BypassOnLocal": true } } ``` Replace the following: - `PROXY_ADDRESS`: The forward proxy URL including port, for example `http://proxy.example.com:8080`. - `PROXY_USERNAME`: The username for proxy authentication. Leave empty for non-authenticated proxies. - `PROXY_PASSWORD`: The password for proxy authentication. Leave empty for non-authenticated proxies. 1. Restart the service for the changes to take effect. The following table describes the `ForwardProxy` properties: | Property | Description | |----------|-------------| | `Address` | Proxy address, for example `http://proxy.example.com:8080`. | | `Username` | Username for proxy authentication. Leave empty for non-authenticated proxies. | | `Password` | Password for proxy authentication. Leave empty for non-authenticated proxies. | | `BypassOnLocal` | Whether to bypass the proxy for local addresses. Defaults to `true`. | ## Use the CLI utility The LGS includes a command-line interface utility designed to manage and borrow license keys associated with your Pdftools products. **note: When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS.** ### Borrow a license Borrowing means adding license keys to the LGS to validate them for the machines in your local network automatically. To borrow a license, use the following command and include the license key: ```shell ptl add LICENSE_KEY_VALUE ``` Replace `LICENSE_KEY_VALUE` with your license key. When you run this command, a connection is opened between the LGS and the Pdftools Licensing Server to validate the license key for a period of time. The LGS lets you use multiple license keys at the same time. **info: In connected mode, you can use the same license key on multiple machines simultaneously. The LGS lets you validate license keys across as many machines as needed in your local network.** ### Check licenses and the service status To view all license keys added to the system, use the following command: ```shell ptl list ``` To view the connection status between the LGS and the Pdftools Licensing Service, use the following command: ```shell ptl status ``` ### Synchronize licenses To establish an active connection between the LGS and the Pdftools Licensing Server manually, use the command: ```shell ptl sync ``` This command contacts the Pdftools Licensing Server and synchronizes usage using the cached data stored by the LGS. ### Return a license To return a borrowed license, use the `remove` command. You must perform the step to return the license to the Pdftools Licensing Server before it can be added to another machine. ```shell ptl remove LICENSE_KEY_VALUE ``` Replace `LICENSE_KEY_VALUE` with your license key. **caution: A license remains borrowed by a specific machine until it is returned, even if it becomes deactivated.** Return the license before another machine can borrow it. To return all license keys added to the LGS, use the command: ```shell ptl remove-all ``` ### LGS CLI commands To access a full list of available commands, use the `ptl help` command. | Command | Description | | --------------------------------------------- | ------------------------------------------------------------------------------ | | `ptl help` | Get instructions on how to use the CLI with a full list of commands. | | `ptl version` | Get the LGS version number. | | `ptl add LICENSE_KEY_VALUE` | Add a new license key. | | `ptl remove LICENSE_KEY_VALUE` | Remove a license key. | | `ptl remove-all` | Remove all license keys. | | `ptl status` | Check the licensing service status. | | `ptl list` | Get information about added license keys and for how long they are valid. | | `ptl sync` | Connect to Pdftools Licensing Server on demand (refreshes the time on all borrowed licenses). | ## Connected mode with Pdftools OCR Service If you configured the connected mode with the Pdftools OCR Service, update your worker nodes configuration. Follow the steps described in [Configuration in connected mode and full offline mode](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license#configuration-in-connected-mode-and-full-offline-mode) section. --- ## Full offline mode Use the Pdftools software fully offline with valid license keys for at least three months or more, depending on your license. Your local network can stay without an internet connection, and license keys are validated for a set period of time. :::info[Multi-machine license activation] Activate the same license key on up to 10 offline LGS machines. Follow the [License key activation](#license-key-activation) steps on each machine. To activate on more than 10 machines, contact Pdftools through the [Contact form](https://www.pdf-tools.com/contact/). :::note[Limitations of full offline mode] The full offline mode **isn't** available for the free trial license keys created in the [Pdftools Portal](https://portal.pdf-tools.com/). For Docker deployments, review [Full offline mode in Docker](https://www.pdf-tools.com/docs/licenses/configure/docker-licensing-gateway-service#full-offline-mode-in-docker). ## Before you start Make sure your license key supports full offline mode. Whether you can use offline mode depends on the order form and quote you accepted from Pdftools. If you require an upgrade to get this feature, contact Pdftools through the [Contact form](https://www.pdf-tools.com/contact/). ## Activate one license key on multiple machines Multi-machine activation requires LGS version 1.3.1030 or later. :::tip[Check LGS version] To check the version of your LGS installation, run the following command: ```bash ptl --version ``` A single license key supports activation on up to 10 separate offline LGS machines. Each machine requires its own LGS installation, configuration, and a separate activation. Deactivating on one machine doesn’t affect the other machines using the same license key. To activate the same license key on multiple machines: 1. Install and configure the LGS on each offline machine as described in [Install the LGS](#install-the-lgs) and [Configure the LGS for offline use](#configure-the-lgs-for-offline-use). 1. Activate the license key on each machine individually by following the steps in [License key activation](#license-key-activation). 1. Reactivate the license key on each machine before the 365-day activation period expires, as described in [License key reactivation](#license-key-reactivation). To activate the same license key on more than 10 machines, contact Pdftools through the [Contact form](https://www.pdf-tools.com/contact/). ## Install the LGS Install the LGS to set up fully offline configuration. Download and install the package on a machine in your network that is **not** connected to the internet. :::caution[LGS is installed with the Conversion Service on Windows Server] - The Conversion Service comes with the LGS preinstalled on Windows. Installing the LGS on such a machine for the second time may render the Conversion Service unusable. For more details, review the implementation of the [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license#licensing-gateway-service) in the Conversion Service licensing documentation. - The full offline mode is available in the Conversion Service version 6+. **Configure the full offline mode** using steps described in [Full offline mode license activation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license#full-offline-mode-license-activation) section. :::info[Conversion Service and LGS on another machine] If you want to install the LGS on another machine than the one where you run the Conversion Service, follow the steps in this section [Install the LGS](#install-the-lgs), and then continue with [Full offline mode license activation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license#full-offline-mode-license-activation) section. **Windows:** 1. Download the LicensingGatewayService.msi package. 1. Run the installer. The installer also creates a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server. **Linux:** :::info[Prerequisite] On Linux systems, the LGS requires **glibc 2.34+**. 1. Download the licgwy_amd64.snap package. 1. Install the snap package: ```bash snap install licgwy_amd64.snap --classic --dangerous ``` The installer also creates a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server. :::info[CLI naming] On Linux, the CLI command name depends on which snap package is installed: - On the **offline machine** (`licgwy` snap): invoke the CLI as `licgwy.ptl`. - On the **online machine** (`ptl` snap): invoke the CLI as `ptl`. To create a shorter alias on the offline machine, run the following command with elevated privileges: ```bash sudo snap alias licgwy.ptl ptl ``` On Windows, the CLI is always `ptl` on both machines. All CLI examples on this page use `ptl` for brevity. ## Configure the LGS for offline use To configure the LGS: 1. Find the LGS configuration file `appsettings.json`: **Windows:** For Windows, the configuration file is in the installation folder, for example: ``` C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json ``` **Linux:** For Linux systems the configuration file is in the `$SNAP_DATA` directory, for example: ``` /var/snap/licgwy/current/appsettings.json ``` Example configuration file: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7, "Endpoints": [] } ``` 1. Turn on offline mode in the LGS. Update the configuration file so that the `IsOfflineMode` property is set to `true`. Example configuration file after update: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7, "IsOfflineMode": true, "Endpoints": [] } ``` 1. Optionally, you can configure these options: - **Licensing Service Port number**: Set the port number used by the service. The default value is `9999`. - **Log file path**: Specify the desired path of the log files. - **Log retention**: Define the number of days the log files remain. - **Endpoints**: An array of stored LGS endpoint URLs for [batch commands](#manage-stored-endpoints). Managed through `ptl endpoints-add` and `ptl endpoints-remove`, but you can also edit this field manually. 1. Restart the service after modifying the `appsettings.json` file so the changes take effect. ## Install the Pdftools Licensing Shell on the online machine To use the CLI-based activation and deactivation workflows, install the Pdftools Licensing Shell (`ptl`) on a machine in your network that is **connected to the internet**. **info: The `ptl` CLI is the same tool used on the offline machine for the LGS. Install the same package on the online machine to access the activation and deactivation commands.** **Windows:** 1. Download the LicensingShell.msi package. 1. Run the installer. **Linux:** 1. Download the ptl_amd64.snap package. 1. Install the snap package: ```bash snap install ptl_amd64.snap --classic --dangerous ``` ## Offline license configuration The following sections explain how to manage your license keys offline using the `ptl` CLI or the Pdftools Portal. You can activate your license in the full offline mode by following the procedures in the following sections: - [Activate license key in the Pdftools Portal](#activate-license-key-in-the-pdftools-portal) - [Activate license key using the CLI](#activate-license-key-using-the-cli) You can deactivate your license in the full offline mode by following the procedures in the following sections: - [Deactivate license key in the Pdftools Portal](#deactivate-license-key-in-the-pdftools-portal) - [Deactivate license key using the CLI](#deactivate-license-key-using-the-cli) ### Prerequisites To use the license keys offline, fulfill the following prerequisites: - The **Pdftools Licensing Shell** (`ptl`) is installed on a machine that is **not** connected to the internet (**offline machine**). - Optional: The **Pdftools Licensing Shell** (`ptl`) is installed on the machine that **is** connected to the internet (**online machine**). This is only necessary in the procedures that involve license key activation and deactivation using the CLI. ### License key activation #### Activate license key in the Pdftools Portal Activate your license key in the full offline mode in the Pdftools Portal by following these steps: 1. On the offline machine with the installed **Licensing Gateway Service**, generate an offline activation token: ```bash ptl export-activation "LICENSE_KEY_VALUE" ``` - Replace `LICENSE_KEY_VALUE` with your license key. 1. Copy the generated **offline activation token** and transfer it to a machine with internet access. 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the [Licenses](https://portal.pdf-tools.com/licenses) tab. 1. Paste the **offline activation token** into the field marked as **Insert your token here...**. 1. Click **Activate**, and then click **Continue**. 1. Copy the generated **license activation token** and transfer it to the offline machine. 1. On the offline machine, activate or extend the license key: ```bash ptl import-activation "LICENSE_ACTIVATION_TOKEN" ``` - Replace `LICENSE_ACTIVATION_TOKEN` with your license activation token from the previous step. The license is activated or extended and ready for use. **note: When you activate a license key in the LGS, it's linked to that machine. You can activate the same license key on up to 10 offline LGS machines without deactivating it first.** #### Activate license key using the CLI Activate your license key in the full offline mode using the `ptl` CLI by following these steps: 1. On the offline machine with the installed **Licensing Gateway Service**, generate an offline activation token: ```bash ptl export-activation "LICENSE_KEY_VALUE" ``` - Replace `LICENSE_KEY_VALUE` with your license key. 1. Copy the generated **offline activation token** and transfer it to the online machine. 1. On the online machine with the installed **Pdftools Licensing Shell**, activate the token: ```bash ptl activate "OFFLINE_ACTIVATION_TOKEN" ``` - Replace `OFFLINE_ACTIVATION_TOKEN` with the offline activation token from the previous step. 1. Copy the generated **license activation token** and transfer it to the offline machine. 1. On the offline machine, activate or extend the license key: ```bash ptl import-activation "LICENSE_ACTIVATION_TOKEN" ``` - Replace `LICENSE_ACTIVATION_TOKEN` with your license activation token from the previous step. The license is activated or extended and ready for use. **note: When you activate a license key in the LGS, it's linked to that machine. You can activate the same license key on up to 10 offline LGS machines without deactivating it first.** ### License key deactivation Although you can activate a license key on up to 10 machines, deactivate the license key on machines you plan to retire. If a machine with an active license key becomes permanently inaccessible, the activation slot remains occupied. If all slots are used, contact Pdftools support to free an activation. Review the [Support page](https://portal.pdf-tools.com/support). #### Deactivate license key in the Pdftools Portal Deactivate your license key in the full offline mode in the Pdftools Portal by following these steps: 1. On the offline machine with the installed **LGS**, locally deactivate the license key: ```bash ptl export-deactivation "LICENSE_KEY_VALUE" ``` - Replace `LICENSE_KEY_VALUE` with your license key. - You can't generate a new activation request token for the same license key until you complete all deactivation steps. 1. Copy the generated **license deactivation request token** and transfer it to a machine with internet access. 1. Log in to [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the [Licenses](https://portal.pdf-tools.com/licenses) tab. 1. Click **Deactivate**. 1. Paste the **license deactivation request token** into the field marked as **Insert your token here...**. 1. Click **Deactivate**, and then click **Continue**. 1. Copy the generated **license deactivation token** and transfer it to the offline machine. 1. On the offline machine, deactivate the license key: ```bash ptl import-deactivation "LICENSE_DEACTIVATION_TOKEN" ``` - Replace `LICENSE_DEACTIVATION_TOKEN` with your license deactivation token from the previous step. The license is removed from the system. If necessary, you can generate a new activation request token for this license key. #### Deactivate license key using the CLI Deactivate your license key in the full offline mode using the `ptl` CLI by following these steps: 1. On the offline machine with the installed **LGS**, locally deactivate the license key: ```bash ptl export-deactivation "LICENSE_KEY_VALUE" ``` - Replace `LICENSE_KEY_VALUE` with your license key. - You can't generate a new activation request token for the same license key until you complete all deactivation steps. 1. Copy the generated **license deactivation request token** and transfer it to the online machine. 1. On the online machine with the installed **Pdftools Licensing Shell**, deactivate the token: ```bash ptl deactivate "OFFLINE_DEACTIVATION_TOKEN" ``` - Replace `OFFLINE_DEACTIVATION_TOKEN` with the token from the previous step. 1. Copy the generated **license deactivation token** and transfer it to the offline machine. 1. On the offline machine, deactivate the license key: ```bash ptl import-deactivation "LICENSE_DEACTIVATION_TOKEN" ``` - Replace `LICENSE_DEACTIVATION_TOKEN` with your license deactivation token from the previous step. The license is removed from the system. If necessary, you can generate a new activation request token for this license key. ## Manage stored endpoints When managing multiple LGS instances, save frequently used endpoint URLs so you don't have to specify them on every batch command invocation. | Command | Description | |---------|-------------| | `ptl endpoints-add ` | Save an LGS endpoint URL (must be a valid HTTP or HTTPS URL). | | `ptl endpoints-remove ` | Remove a stored endpoint. | | `ptl endpoints-list` | List all stored endpoints. | Stored endpoints are saved in the `"Endpoints"` array in `appsettings.json`. You can also edit this field manually. When [batch commands](#batch-activation-across-multiple-lgs-instances) (`activate-all`, `deactivate-all`, `batch-export-activation`, `batch-export-deactivation`) are called **without** endpoint URL arguments, they automatically use the stored endpoints. Endpoint URLs provided on the command line always take priority over stored ones. ## Batch activation across multiple LGS instances To activate the same license key across multiple LGS instances, such as several Docker containers, Linux servers, or Windows machines, use the batch commands. The machine running `ptl` must be able to reach all listed LGS endpoints over the network. Whether internet access is also required depends on whether you use the Pdftools Portal or a fully offline CLI workflow. :::tip[Stored endpoints] Save your LGS endpoint URLs with `ptl endpoints-add` to avoid specifying them on every batch command. For details, refer to [Manage stored endpoints](#manage-stored-endpoints). ### Batch activation #### Batch activate in the Pdftools Portal Activate a license key across multiple LGS instances using the Pdftools Portal by following these steps: 1. Generate a batch activation token from all LGS endpoints: ```bash ptl batch-export-activation "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances (for example, `http://localhost:9991` `http://localhost:9992`). Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). 1. Copy the generated **batch activation token**. If the machine running `ptl` doesn't have internet access, transfer the token to a machine that does. 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the [Licenses](https://portal.pdf-tools.com/licenses) tab. 1. Paste the **batch activation token** into the field marked as **Insert your token here...**. 1. Click **Activate**, and then click **Continue**. 1. Copy the generated **license activation token**. If necessary, transfer it back to the machine running `ptl`. 1. Import the activation across all LGS instances: ```bash ptl batch-import-activation "LICENSE_ACTIVATION_TOKEN" ``` - Replace `LICENSE_ACTIVATION_TOKEN` with the token from the previous step. The license key is activated across all specified LGS instances. #### Batch activate using the CLI If the machine running `ptl` has internet access, activate a license key across multiple LGS instances by following these steps: 1. Generate a batch activation token from all LGS endpoints: ```bash ptl batch-export-activation "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances. Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). 1. Copy the generated **batch activation token**. 1. Activate the token online: ```bash ptl activate "BATCH_ACTIVATION_TOKEN" ``` - Replace `BATCH_ACTIVATION_TOKEN` with the token from the previous step. The `activate` command auto-detects batch tokens. 1. Copy the generated **license activation token**. 1. Import the activation across all LGS instances: ```bash ptl batch-import-activation "LICENSE_ACTIVATION_TOKEN" ``` - Replace `LICENSE_ACTIVATION_TOKEN` with the token from the previous step. The license key is activated across all specified LGS instances. #### Shortcut: activate-all If the machine running `ptl` has internet access, use the `activate-all` command as a shortcut that combines the export, activate, and import steps: ```bash ptl activate-all "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances. Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). ### Batch deactivation #### Batch deactivate in the Pdftools Portal Deactivate a license key across multiple LGS instances using the Pdftools Portal by following these steps: 1. Generate a batch deactivation token from all LGS endpoints: ```bash ptl batch-export-deactivation "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances. Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). 1. Copy the generated **batch deactivation token**. If the machine running `ptl` doesn't have internet access, transfer the token to a machine that does. 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the [Licenses](https://portal.pdf-tools.com/licenses) tab. 1. Click **Deactivate**. 1. Paste the **batch deactivation token** into the field marked as **Insert your token here...**. 1. Click **Deactivate**, and then click **Continue**. 1. Copy the generated **license deactivation token**. If necessary, transfer it back to the machine running `ptl`. 1. Import the deactivation across all LGS instances: ```bash ptl batch-import-deactivation "LICENSE_DEACTIVATION_TOKEN" ``` - Replace `LICENSE_DEACTIVATION_TOKEN` with the token from the previous step. The license key is deactivated across all specified LGS instances. #### Batch deactivate using the CLI If the machine running `ptl` has internet access, deactivate a license key across multiple LGS instances by following these steps: 1. Generate a batch deactivation token from all LGS endpoints: ```bash ptl batch-export-deactivation "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances. Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). 1. Copy the generated **batch deactivation token**. 1. Deactivate the token online: ```bash ptl deactivate "BATCH_DEACTIVATION_TOKEN" ``` - Replace `BATCH_DEACTIVATION_TOKEN` with the token from the previous step. The `deactivate` command auto-detects batch tokens. 1. Copy the generated **license deactivation token**. 1. Import the deactivation across all LGS instances: ```bash ptl batch-import-deactivation "LICENSE_DEACTIVATION_TOKEN" ``` - Replace `LICENSE_DEACTIVATION_TOKEN` with the token from the previous step. The license key is deactivated across all specified LGS instances. #### Shortcut: deactivate-all If the machine running `ptl` has internet access, use the `deactivate-all` command as a shortcut that combines the export, deactivate, and import steps: ```bash ptl deactivate-all "LICENSE_KEY_VALUE" ENDPOINT_1 ENDPOINT_2 ``` - Replace `LICENSE_KEY_VALUE` with your license key. - Replace `ENDPOINT_1 ENDPOINT_2` with the addresses of your LGS instances. Omit the endpoint arguments to use [stored endpoints](#manage-stored-endpoints). ## License key reactivation The activated license key is valid in the full offline mode for 365 days. Reactivate the license key to extend this period for another 365 days. The license expiration date is independent of this activation period. For example: - Your license key expires in two years. You can reactivate the license key for full offline mode before or after the 365-day period expires. This will reset the offline activation license period to another 365 days. - Your license key expires in six months. Your offline activation period is displayed as 365 days. Your license key stops working after 6 months, but the license key activation period still displays 182 days remaining. You can reactivate your license at any time. Reactivation only resets the full offline mode activation period to 365 days. Reactivate the license key before the activation period expires to ensure uninterrupted use. If you reactivate after the activation period expires, the license stops working until you complete the reactivation. To reactivate your license key: 1. Repeat the activation steps as described in [License key activation](#license-key-activation) section. :::info[Multi-machine reactivation] If you activated the same license key on multiple offline LGS machines, reactivate it on each machine individually. Complete the reactivation before the 365-day activation period expires. ## References The following section lists the `ptl` CLI commands for managing licenses in the fully offline configuration. ### CLI commands The Pdftools Licensing Shell (`ptl`) is a command-line interface for managing licenses associated with your Pdftools products. To access a full list of available commands, use the `ptl help` command. #### General commands | Command | Description | |---------|-------------| | `ptl help` | Get instructions on how to use the CLI with a full list of commands. | | `ptl version` | Get the version number. | | `ptl status` | Check the licensing service status. | | `ptl list` | Get information about added license keys and for how long they are valid. | #### Single-instance offline commands (run on the offline machine) | Command | Description | |---------|-------------| | `ptl export-activation LICENSE_KEY_VALUE` | Export an activation request. | | `ptl import-activation LICENSE_ACTIVATION_TOKEN` | Import an activation response. | | `ptl export-deactivation LICENSE_KEY_VALUE` | Export a deactivation request. | | `ptl import-deactivation LICENSE_DEACTIVATION_TOKEN` | Import a deactivation response. | #### Online activation and deactivation commands (run on the online machine) | Command | Description | |---------|-------------| | `ptl activate TOKEN` | Activate an offline token. Auto-detects single and batch tokens. | | `ptl deactivate TOKEN` | Deactivate an offline token. Auto-detects single and batch tokens. | #### Batch commands (for multiple LGS instances) | Command | Description | |---------|-------------| | `ptl activate-all LICENSE_KEY [ENDPOINT...]` | Activate a license key across multiple LGS endpoints in one step. | | `ptl deactivate-all LICENSE_KEY [ENDPOINT...]` | Deactivate a license key across multiple LGS endpoints in one step. | | `ptl batch-export-activation LICENSE_KEY [ENDPOINT...]` | Export a batch activation token from multiple LGS endpoints. | | `ptl batch-import-activation TOKEN` | Import a batch activation response to all LGS endpoints. | | `ptl batch-export-deactivation LICENSE_KEY [ENDPOINT...]` | Export a batch deactivation token from multiple LGS endpoints. | | `ptl batch-import-deactivation TOKEN` | Import a batch deactivation response to all LGS endpoints. | #### Endpoint management commands | Command | Description | |---------|-------------| | `ptl endpoints-add ` | Save an LGS endpoint URL. | | `ptl endpoints-remove ` | Remove a stored endpoint. | | `ptl endpoints-list` | List all stored endpoints. | ## Full offline mode with Pdftools OCR Service If you configured the full offline mode with the Pdftools OCR Service, update your worker nodes configuration. Follow the steps described in [Configuration in connected mode and full offline mode](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license#configuration-in-connected-mode-and-full-offline-mode) section. --- ## Configure SSL Learn how to configure the Pdftools Licensing Gateway Service (LGS) to use the SSL and create HTTPS communication for your license key validation. **info: Before configuring SSL with the LGS, review [Configure the LGS](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service#configure-the-lgs) section.** ## SSL configuration To enable SSL compatibility with LGS, follow these steps depending on your operating system: **Windows:** 1. Find the `appsettings.json` LGS configuration file. It is located in the installation folder. For example: ``` C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json ``` 2. Add the following keys to your configuration file. - Specify the port where SSL communication occurs: ``` LicensingServiceHTTPSPortNumber: 9990 ``` - Add path to the certificate file: ``` CertPemFile: C:/certs/certificate.pem ``` - Add path to the private key file: ``` CertKeyFile: C:/certs/privatekey.key ``` :::warning Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication. ::: 3. Example configuration file: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7, "IsOfflineMode": false, "LicensingServiceHTTPSPortNumber": 9990, "CertPemFile": "C:/certs/cert.pem", "CertKeyFile": "C:/certs/private-key.key" } ``` 4. Restart service after changing configuration by running the following command: ```powershell Stop-Service -Name "Licensing Gateway Service" Start-Service -Name "Licensing Gateway Service" ``` **Linux:** 1. Find the `appsettings.json` LGS configuration file. It is located in the `$SNAP_DATA` directory. For example: ``` /var/snap/licgwy/current/appsettings.json ``` 2. Add the following keys to your configuration file. - Specify the port where SSL communication occurs: ``` LicensingServiceHTTPSPortNumber: 9990 ``` - Add path to the certificate file: ``` CertPemFile: C:/certs/certificate.pem ``` - Add path to the private key file: ``` CertKeyFile: C:/certs/privatekey.key ``` :::warning Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication. ::: 3. Example configuration file: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "/usr/share/Pdftools/lgs/logs/log.txt", "LogRetentionDays": 7, "IsOfflineMode": false, "LicensingServiceHTTPSPortNumber": 9990, "CertPemFile": "/etc/lgs/ssl/cert.pem", "CertKeyFile": "/etc/lgs/ssl/private-key.key" } ``` 4. Restart service after changing configuration by running the following command: ```bash sudo snap restart licgwy ``` **Docker:** 1. Add the following keys to your configuration file. - Specify the port where SSL communication occurs: ``` LicensingServiceHTTPSPortNumber: 9990 ``` - Add path to the certificate file: ``` CertPemFile: C:/certs/certificate.pem ``` - Add path to the private key file: ``` CertKeyFile: C:/certs/privatekey.key ``` :::warning Include all files and configuration keys mentioned above. If you miss any of them the LGS doesn't activate SSL and defaults to HTTP communication. ::: 2. Example of the complete run command: ```bash docker run --name lgsdocker \ -e LICENSE_KEYS="YOUR_LICENSE_KEY" \ -e LicensingServicePortNumber=9999 \ -e LicensingServiceHTTPSPortNumber=9990 \ -e CertPemFile=/etc/lgs/ssl/cert.pem \ -e CertKeyFile=/etc/lgs/ssl/private-key.pem \ -v /etc/lgs/ssl/:/etc/lgs/ssl/ \ -p 9999:9999 \ -p 9990:9990 \ -d \ pdftoolsag/license-gateway:latest ``` - Replace `YOUR_LICENSE_KEY` with the value of your license key. - Ensure that you certificates are reachable by storing them at `/etc/lgs/ssl/` in your host system. You can alternatively replace and customise all port numbers, values, and file paths, but ensure to edit the previous command example accordingly. If your configuration is correct, the LGS logs include information similar to: ``` [Information] Now listening on: "https://[::]:9990" ``` --- ## Pdftools Portal The [Pdftools Portal](https://portal.pdf-tools.com/) lets you manage your licenses, account settings, users, and notification preferences. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to access the portal. The portal sidebar provides access to the following sections: - **Products**: An overview of your products and license keys. - **Licenses**: Activate and deactivate license keys offline, and process legacy offline licensing files. - **Utilities and tools**: Access additional tools and utilities. - **Support**: Open support requests, access documentation resources, upload files for the support team, and contact your dedicated customer success manager. :::info[Legacy customer portal users] The legacy customer portal is no longer available. Your assigned customer success manager sends quotes, invoices, and contracts directly through email. To find your customer success manager's contact details, go to the **Support** tab in the [Pdftools Portal](https://portal.pdf-tools.com/). For any other questions, use the [Contact page](https://www.pdf-tools.com/contact/). ## Products The **Products** tab is the landing page of the portal and displays all your products in two categories: - **Products**: Your active Pdftools products (Pdftools SDK, Toolbox add-on, PDF Viewer SDK, Conversion Service, and others). - **Legacy Products**: Products from the previous product line. To view the license keys for a product, select **See product**. Each product page displays the following information for every license key: - **License key**: The license key string. Select **Click to copy** to copy it to your clipboard. - **Status**: Whether the license key is active. - **Maintenance End**: The date your maintenance contract expires. Renew your contract before this date to maintain access to updates and support. - **Page Credits**: The number of page credits used and the total allocation for that key. Some keys display **Unlimited usage** instead. - **Trial Period**: For trial keys, the remaining trial days and a progress bar. Each product page also includes a **Product Builds** section where you can download the product binaries. Select a version from the dropdown, filter by programming language or architecture, and select **Download** for the artifact you need. Some packages link to external repositories (NuGet, Maven Central, PyPI). ## Licenses The **Licenses** tab lets you activate and deactivate license keys for offline use, and process legacy offline licensing files. ### Offline license activation and deactivation To activate a license key offline, go to **Licenses**, select the **Activate** tab, and paste the activation token into the text field. To deactivate, select the **Deactivate** tab. For more information about generating activation tokens and configuring offline licensing, review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service). ### Legacy offline licensing Upload a legacy license activation or deactivation file (`.bin`) to process it. Select **Choose .bin file** and upload the file. This feature is for customers who used the legacy offline licensing system before the migration to the Pdftools Portal. For more information about legacy licensing, review [Legacy SDK product licensing](https://www.pdf-tools.com/docs/licenses/products/3-heights-licenses). ## Support The **Support** tab lets you open support requests, access documentation resources, and contact your dedicated customer success manager. For details on how to open a support request, review [Pdftools Technical Support](https://www.pdf-tools.com/docs/support/). ## Manage notifications Notification settings let you control which users in your organization receive email notifications about licensing events, such as license key expiration reminders, renewal notices, and page credit consumption alerts. To manage notification settings: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Select the profile icon in the bottom-left corner of the sidebar. 1. Select **Notification Settings**. 1. In the **Licensing Email Notifications** section, use the toggle next to each user to turn on or turn off their email notifications. 1. Select **Save**. ## Manage users The **Users** section lets you manage who has access to your organization's account in the Pdftools Portal. Add team members so they can view license keys, manage products, and receive notifications. To manage users: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Select the profile icon in the bottom-left corner of the sidebar. 1. Select **Account Settings**. 1. Under **Workspace**, select **Users**. From this page, you can: - **Invite a user**: Select **Invite User** and enter the email address of the person you want to add. - **Search users**: Use the search field to find users by email. - **View user details**: The table displays each user's full name, email, role, and status. - **Manage user options**: Select the options icon next to a user to view available actions. --- ## 3-Heights SDK product licensing Licenses for 3-Heights SDK products are managed using the License Manager. For more licensing related information, see the [Technical Note: License keys](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys3Heights.pdf). ## Find 3-Heights product license To find and copy a license key: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, go to the **Legacy Products** section. 1. Next to your 3-Heights product, click **See product**. 1. Next to the product license key, click **Click to copy**. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs. --- ## Conversion Service licensing Learn how to activate and configure license keys for the Conversion Service. :::info[Product documentation] For information about using the Conversion Service, review [Conversion Service documentation](https://www.pdf-tools.com/docs/conversion-service/). This page includes details about one of the Pdftools products. For a general overview of different licenses of Pdftools products, see [Licenses of Pdftools products](https://www.pdf-tools.com/docs/licenses/). ## Get trial license To try or fully use the Conversion Service, you must obtain a license key. To get the Conversion Service evaluation license key for free, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service Trial**, click the **Copy **. You now have a free trial license key. Its limitations are the following: - The converted files have a watermark - The license key is limited to 90 days. **note: The trial license key is valid for 90 days starting at UTC time. The Pdftools Portal indicates the validity period starting at 89 days (as the consumption of the first day already started). This period may slightly vary depending on your time zone relative to UTC.** ## Request full license **tip: You can try the Conversion Service for free with a trial license key. In this section, you can learn how to request a full license key.** To request a full license key, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Request license**. 1. On the **Contact us** window, fill in the requested fields, and then click **Submit**. ## Find the Conversion Service license key To find and copy a license key: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Conversion Service, click **Get started** or **See product**. 1. Next to the **Conversion Service Trial** or **Active**, click **Click to copy **. ## Add or remove a license key If you are running the Conversion Service on **Windows systems**, add a license key in your Conversion Service license tab by the following steps: 1. In the Conversion Service Configurator, click **License** tab. 2. Paste the license key into the **Key** field and click **Add**. To remove a license key: 1. In the Conversion Service Configurator, click **License** tab. 2. Under the **License Information** section, next to the **Key** field, click **Remove**. Review the following links for information about the Conversion Service license key management in Docker: - For stand-alone Docker containers, review [Manage license keys](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container/#manage-license-keys) documentation. - For Docker Compose containers, review [Configure containers using Docker Compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose) documentation. The Conversion Service uses the Licensing Gateway Service (LGS) to validate the license keys. The LGS is preinstalled with the Conversion Service and requires an internet connection to validate the license keys. Read the [Licensing Gateway Service](#licensing-gateway-service) section for more information. ## Licensing credit count The Conversion Service charges page credits for every successfully converted document page. These page credits also apply to attached and embedded documents. Processing a PDF/A page costs two extra page credit. The number of page credits charged depends on the specific workflow selected: | Workflow | Page credits | | --------------- | --------------------------------------------------------------- | | Conversion | 1 | | Archive PDF/A-2 | 2 | | Archive PDF/A-3 | 2 | | Archive PDF/A-1 | 2 | | Dossier | 1, 2, or free (review [Dossier credits](#dossier-page-credits)) | | Invoice | 2 | | Archive TIFF | 1 | | Sign | 1 | | Extraction | 1 | ### Dossier page credits **info: The [Dossier workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier) lets you assemble several PDF documents into a single dossier with extended functionality, such as a title page and table of contents.** The number of page credits calculated for the Dossier workflow depends on the selected preprocessing workflow: - Any Archive workflow (Archive PDF/A-2, Archive PDF/A-3, Archive PDF/A-1) costs **two** page credits (the same price as just the conversion to PDF/A-2 without a dossier). - The Conversion workflow costs **one** page credits. - If you don't select a preprocessing step, assembling a dossier costs **no** page credits. ### Remaining page credit count To review the remaining page credits in your license usage quote, you can review your license usage: - In the [Pdftools Portal](https://portal.pdf-tools.com/). For more information, review [View page credits consumption in the Pdftools Portal](#view-page-credits-consumption-in-the-pdftools-portal). - In the Conversion Service Configurator. For more information, review [View page credits consumption in the Conversion Service Configurator](#view-page-credits-consumption-in-the-conversion-service-configurator). If you are using a version of the Conversion Service prior to 6.6.0, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get information about the remaining page credit count. #### View page credits consumption in the Pdftools Portal 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. In the **Products** tab, click **See product** next to the Conversion Service. 1. Find your page credits usage in a specific section that lists your license key. On this page, you can review your total number of page credits, number of used credits, license key expiration, and more. #### View page credits consumption in the Conversion Service Configurator 1. In the Conversion Service Configurator, open the **License** tab. 1. Review the percentage of used page credits in the **Properties** section. ## Licensing Gateway Service In the background, the Conversion Service uses the **Licensing Gateway Service (LGS)** to activate and use a license key or to report the number of used page credits to Pdftools. The LGS connects to the Pdftools Licensing Service to validate the installed license key and transmit the number of processed pages. Since version 4.7 of the Conversion Service, the LGS is installed locally with the Conversion Service on Microsoft Windows systems. To configure the firewall service correctly, note that the LGS connects through port 443 (SSL) to the Pdftools Licensing Service hosted at `https://licensing.pdf-tools.com/`. :::info[Privacy] Pdftools does **not** receive information about documents and data processed by the Conversion Service other than the hostname and the number of processed pages. At Pdftools, we highly value our customers' privacy. ### Internet access The LGS requires an internet connection. The Conversion Service uses LGS to add or remove a license key, or to report the number of used page credits to Pdftools. If you lose the internet connection, the license key remains active for: - Seven days - Professional and Business plan - 30 days - Enterprise plan You are prompted with a configuration error if the gateway refuses to consume page credits due to an invalid license or lack of internet connection. Details about the error are in the Conversion Service log. For more information, review [Troubleshooting](#troubleshooting) section. :::note[Fully offline access] Contact the Pdftools Customer Success team to discuss fully offline access to the Conversion Service. This option is available for the **Enterprise** plan users. ### Manage multiple Conversion Service installations All your Conversion Service instances can use the same license key activated in one LGS. You can use the same LGS as the one that is preinstalled by default with the Conversion Service, or you can install the LGS separately without the Conversion Service. The system that sends the usage data must have an internet connection. In a nutshell, to have multiple systems running the Conversion Service using a single license key: - Change the LGS address to the address of a system that sends the usage data. - The system that sends usage data needs to maintain an internet connection. - This system needs to have the LGS installed. You can install the LGS: - Automatically with the Conversion Service. - Separately without the Conversion Service. For example, there are computers A, B, and C in the local network. Computers B and C send usage data to computer A. A then sends data to Pdftools. To create this setup: - Computer A needs to have the LGS installed and configured. - Computers B and C need to have the local network address of A added in the Conversion Service Configurator. :::note[Multiple license keys] It is possible but not required to activate different instances with multiple license keys. Multiple license keys can be issued under specific circumstances. When Windows and Docker-based Conversion Service is running simultaneously, or if you use an older licensing model based on a number of cores. For more details, review [Legacy core-based license key](#legacy-core-based-license-key) section. For specific steps, configure the LGS as described in the following [Prerequisites](#prerequisites) and [Change the Licensing Gateway Service address in the Conversion Service](#change-the-licensing-gateway-service-address-in-the-conversion-service) sections. #### Prerequisites Ensure you have an LGS set up and that your license key is activated. If you choose to install the LGS separately without the Conversion Service, make sure that this system has an internet connection to communicate with the Pdftools Licensing Service. For detailed instructions on how to install and interact with the LGS, review [Install the LGS](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service#install-the-lgs). #### Change the Licensing Gateway Service address in the Conversion Service For each Conversion Service instance, add the address of the system that hosts the Licensing Gateway Service (LGS), which also maintains the internet connection with Pdftools. **note: If you activated a license key before, you must remove it first. To remove the license key:** 1. In the Conversion Service Configurator, go to the **License** tab. 2. Copy the license key from the **Key** field. 3. Click **Remove**, and then **OK**. Configure the LGS address by the following steps: 1. In the Conversion Service Configurator, go to the **License** tab. 2. In **Configuration**, change the **License Gateway Address** field to the specific computer address in your network that has LGS installed. 3. Click **Save** or **Save & Restart**. 4. Paste the license key to the **Key** field, and then click **Add**. :::info[Activate Conversion Service license key in Docker] If you are using the Conversion Service in Docker, change the address of the Licensing Gateway Service using the environment variable `LICENSINGSERVICE`. Find more details in the [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/) getting started guide, specifically in the last steps of the procedure documented in the [Configure and export a profile](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/#configure-and-export-a-profile) section. ### Full offline mode license activation Use the Conversion Service fully offline with valid license keys for at least three months or more, depending on your license. #### Configure offline mode Configure the Licensing Gateway Service (LGS) for offline use: 1. Locate the LGS configuration file `appsettings.json`. The configuration file is in the installation folder, for example: ``` C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json ``` 1. Update the configuration file so that the `IsOfflineMode` property is set to `true`. Example configuration file: ```json { "LicensingServicePortNumber": 9999, "LogFilePath": "C:/logs/pdftls/log.txt", "LogRetentionDays": 7, "IsOfflineMode": true } ``` 1. Restart the Licensing Gateway Service. 1. Go to the **Conversion Service Configurator** > **License** tab. 1. Click **Refresh ** button next to the **Licensing Gateway Mode** field, or restart the Configurator. 1. Verify that the **Licensing Gateway Mode** displays **Full Offline**. #### Add license key To add a license key in full offline mode: 1. In the Conversion Service Configurator, select the **License** tab, enter your license key in the **Key** field, and then click **Add**. 1. Optional: In the Activation Wizard, you can change the pre-populated **Computer Name** field with another machine name. 1. Click **Generate Token**. The generated token is valid for 24 hours. 1. Click **Copy** button to copy the token, and then click **Next**. The Activation Wizard displays the guidance for the next steps. 1. Optional: If the machine running the Configurator doesn't have internet access, transfer the token to a machine that does. 1. Open the [Pdftools Portal](https://portal.pdf-tools.com/licenses) in a web browser. 1. Select the **Activate** tab, and then paste the token into the field marked as **Insert your token here**. 1. Click **Activate**. 1. Click **Copy** to copy the response token. 1. Optional: If you accessed the Portal from a different machine, transfer the response token back to the machine running the Configurator. 1. In the Configurator, click **Next**. 1. Press `Ctrl` + `v` or click the paste icon to paste the token into the text field. 1. Click **Apply**. The license is added. The Configurator displays the **License Expiration Date** and **Token Validity**. :::tip[License expiration and token validity] The **License** tab displays two dates related to the offline activation: - **License expiration** - The date when the license key expires. - **Sync** - Number of days for which offline activation is valid. Both of these values must be valid for the license to work in the full offline mode. These values are independent. Your license key can expire before or after the full offline mode activation period. To extend the token validity period, review [Reactivate license key](#reactivate-license-key). #### Reactivate license key To extend the token validity for a license key in the full offline mode, follow these steps: 1. In the Conversion Service Configurator, select the **License** tab. 1. Click **Reactivate**. 1. Follow the same steps as described in section [Add license key](#add-license-key) #### Remove license key To remove a license key in full offline mode: 1. In the Conversion Service Configurator, select the **License** tab, and then click **Remove**. The Offline Deactivation Wizard opens. 1. Click **Generate Token**. The generated token is valid for 24 hours. 1. Optional: Change the pre-populated **Computer Name** field to another machine name. 1. Click **Copy** to copy the token. 1. Click **Next**. 1. Optional: If the machine running the Configurator doesn't have internet access, transfer the token to a machine that does. 1. Open the [Pdftools Portal](https://portal.pdf-tools.com/licenses) in a web browser. 1. Switch to the **Deactivate** tab, and then paste the token into the field marked as **Insert your token here**. 1. Click **Deactivate**. 1. Click **Copy** to copy the response token. 1. Optional: If you accessed the Portal from a different machine, transfer the response token back to the machine running the Configurator. 1. In the Configurator, click **Next**. 1. Press `Ctrl` + `v` or click the paste icon to paste the token into the text box. 1. Click **Apply**. The license key is removed. The Configurator displays only a limited number of tabs (Support Request, License, and About). ## Legacy core-based license key License keys issued before September 2023 use a core-based license. With a core-based license, you can manage the license keys with the legacy License Manager application. There are different options depending on the version of the Conversion Service: - Conversion Service version 4.6 or earlier: Use the legacy License Manager to activate and deactivate core-based license keys. - Conversion Service version 4.7 or higher: You can use both the License tab in the Conversion Service Configurator for the usage-based licensing model or the legacy Licensing Manager to activate and deactivate core-based license keys. - Conversion Service version 5.2 or higher: You can use only the License tab in the Conversion Service Configurator for the usage-based licensing model to activate, update, or deactivate core-based license keys. ### Offline usage for legacy core-based licenses The following actions require internet access: - License key activation - License key update - License key deactivation See the next sections for more information about offline license key activation, update, and deactivation for the legacy core-based licenses. #### Offline license key activation To activate a license key without internet access: 1. In the Conversion Service Configurator, select the **License** tab. 2. Paste your license key in the **Key** field, and then click **Add**. 3. If you are offline, a window appears with a prompt: **You're offline. Follow the steps to activate a license key offline:** 4. Follow the steps as documented within the Conversion Service Configurator. #### Offline license key update To update a license key without internet access: 1. In the Conversion Service Configurator, select the **License** tab. 2. Click **Update**. 3. If you are offline, a window appears with a prompt: **You're offline. Follow the steps to activate a license key offline:** 4. Follow the steps as documented within the Conversion Service Configurator. #### Offline license key deactivation To deactivate a license key without internet access: 1. In the Conversion Service Configurator, select the **License** tab. 2. Click **Remove**. 3. If you are offline, a window appears with a prompt: **You're offline. Follow the steps to activate a license key offline:** 4. Follow the steps as documented within the Conversion Service Configurator. ## Troubleshooting You may encounter problems when adding or using a license. See the following sections for the most common errors. ### Configuration errors During configuration, you can encounter warnings and errors inside the Conversion Service Configurator. These errors and warnings can also prompt you with a resolution of your issue. **Unable to add license key / License key could not be removed** To add and remove a page-based license key, the License Gateway requires an internet connection. **Activation Failed / License key could not be deactivated** **Usage-based licensing**: When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS. For more information, review [License key deactivation](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service#license-key-deactivation). **Core-based licenses**: Most core-based licenses must be activated before they can be used and deactivated before they can be removed. The activation and deactivation process requires an internet connection. If your system is running offline, review [Offline usage](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf#page=13) documentation. ### License validation or consumption errors Some of the warnings and errors that can be encountered during regular use of the service. **License consumption failed (InvalidConfiguration)** There was an error in the consumption of the license page credits. There are several possible reasons for such an error. Use the Conversion Service Configurator to view the current license status and if there are any errors. **Service not available due to a license issue** The validation of the current license failed. Please use the Conversion Service Configurator to view the current license status. --- ## Pdftools OCR Service licensing By default, the [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) requires a network connection to validate the license key with the [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/). Or, you can configure the Pdftools OCR Service to run without a network connection. For more information, see [Configure offline license key validation](#configure-offline-license-key-validation). :::info[Product documentation] For information about using the Pdftools OCR Service, review [Pdftools OCR Service documentation](https://www.pdf-tools.com/docs/ocr-service/). ## Configure offline license key validation If you need the Pdftools OCR Service to operate without a direct internet connection to verify the license key, set up the [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) (LGS). With the LGS, you can configure the Pdftools OCR Service to: - Use a partially offline mode called **connected mode**. For more information, review [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service). - Use **full offline mode**. For more information, review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service). ### Configuration in connected mode and full offline mode #### Prerequisites To let the Pdftools OCR Service operate without a continuous internet connection, install and configure the LGS. Review [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service), or [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service) for specific guidance. #### Procedure After configuring the LGS with the Pdftools OCR Service using the connected mode or full offline mode, follow these steps: 1. Find your worker node's `appsettings.json`. The following is the default path of the worker configuration file: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` 1. Edit the `LgsURL` parameter value to point to the machine where you configured the LGS. The default value is: ``` "LgsURL": "http://localhost:9999" ``` For more information, review [Default appsettings.json](https://www.pdf-tools.com/docs/ocr-service/guides/monitor/#default-appsettingsjson-1) in the Pdftools OCR Service documentation. --- ## PDF Toolbox SDK licensing License for this product is managed using the License Manager. For more licensing related information, review [Technical Note: License Keys](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf). :::info[Product documentation] For information about using the PDF Toolbox SDK, review [PDF Toolbox SDK documentation](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-toolbox-sdk/). Set the license key by using the `Sdk.Initialize` method before calling the library. Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get an evaluation or full license key for the PDF Toolbox SDK. The evaluation license key is necessary to try the PDF Toolbox SDK. --- ## Pdftools SDK license management Learn how to manage the Pdftools SDK license keys. The information on this page applies to legacy and page credit licenses. :::info[Product documentation] For information about using the Pdftools SDK, review the [Pdftools SDK documentation](https://www.pdf-tools.com/docs/pdf-tools-sdk/). ## Request trial or full license You can use the Pdftools SDK and the Pdftools SDK Shell Tool **without a license key** with watermarked results. To get a full license and remove the watermarks, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Click **Contact sales** button. 1. Fill in the required details. 1. Click **Submit**. ## Find the license key To find and copy a license key: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Pdftools SDK entry, click **Get started** or **See product**. 1. Find your license key in the **License keys** section, and then click **Copy **. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs. ## Trial license overview You can use the same license key for the Pdftools SDK, Pdftools Shell Tool, and Toolbox add-on. The Pdftools SDK and Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. ## Licensing credit count Page credit-based pricing charges a page credit for each operation performed on a document page. A page credit is used for: - Each page of a document. - Each operation applied to that page. Review the following table for more information about the credit count in the Pdftools SDK and the Pdftools SDK Shell Tool for specific operations: | Operation | Page credits used | |----------------------------|-------------------| | Archive PDF/A-1 | 2 | | Archive PDF/A-2 | 2 | | Archive PDF/A-3 | 2 | | Compress and optimize | 1 | | Convert | 1 | | Embed e-invoice | 1 | | Extract | 1 | | Merge and split PDFs | 1 | | Archive TIFF | 1 | | Sign and secure | 1 | | Validate | 1 | Only **PDF to PDF/A** conversion is charged at **2 page credits** per operation; all other operations cost **1 page credit**. ### Operations An operation is any action performed on a document using the Pdftools SDK and the Pdftools SDK Shell Tool. Common operations include: - File conversions: Converting files to or from PDF (for example, TIFF to PDF, PDF to image). - Compressing or optimizing PDFs. - Merging files or extracting pages, adding signatures, encrypting, or annotating PDFs. Each time you apply an operation to one or more pages, page credits are charged based on each page affected by the operation. Pages that are not affected by the operation are not charged. For example, if you have a 10-page document and only use the extract operation on five pages, only **5 page credits** are used. ### Calculating credits To determine how many page credits you'll need for your tasks using the Pdftools SDK, follow this formula: **Number of pages x number of operations = total page credits used** For example: - **Three-page PDF, one operation**: Converting a three-page TIFF to PDF requires **3 page credits** (1 per page). - **Three-page PDF, two operations**: Converting a three-page PDF and then compressing it requires **6 page credits** (3 pages x 2 operations). - **Three-page PDF, PDF/A conversion**: Converting a three-page PDF to PDF/A requires **6 page credits** (3 pages x 2 page credits). Page credits are calculated for every operation applied. If multiple actions are performed on a file, page credits are consumed for each operation. For example: - **Four pages, one operation**: Signing four individual pages of PDF costs **4 page credits** (4 pages x 1 operation). - **Four pages, two operations**: Converting and compressing a four-page PDF costs **8 page credits** (4 pages x 2 operations). - **Four pages, three operations**: Converting, compressing, and adding a watermark to a four-page PDF costs **12 page credits** (4 pages x 3 operations). ## License key validation License keys are validated using the [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/). The SDK connects to the Pdftools Licensing Service to provide usage information and retrieve new licensing parameters after processing a document. The Pdftools Licensing Service collects the following statistics and information: - License number - The Pdftools SDK functions used and the number of pages processed For information on managing your license key with the Pdftools Licensing Service, see [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/). ## Initialize the Pdftools SDK license Learn how to use a license key for the Pdftools SDK. Review the appropriate link for your programming language: - [Initialize the SDK C](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-c#optional-initialize-the-sdk) - [Initialize the SDK Java](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java#optional-initialize-the-sdk) - [Initialize the SDK .NET](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-dotnet#optional-initialize-the-sdk) - [Initialize the SDK Python](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python#optional-initialize-the-sdk) - [Initialize the SDK Other languages and frameworks](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-other-languages#use-the-pdftools-sdk-with-go) ## Use the Pdftools SDK Shell Tool license Learn how to use the Pdftools SDK Shell Tool license key: - [Use of license key](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool#use-of-license-key) ## Default license configuration By default, when the Pdftools SDK is initialized, it attempts to directly connect to the Pdftools Licensing Service. This requires an internet connection to the default licensing service URL: ``` https://licensing.pdf-tools.com/api/v1/licenses/ ``` **caution: By default, if the Pdftools SDK cannot connect to the licensing service URL, the SDK initialization fails.** ## Use the Licensing Gateway Use the [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) (LGS) if the Pdftools SDK needs to operate without a direct connection to the Pdftools Licensing Service. To configure the SDK to use the Licensing Gateway Service, set the `LicensingService` property of the `Sdk` class before calling `Sdk.Initialize`. **C:** ```c int main(int argc, char* argv[]) { // Initialize the library PdfTools_Initialize(); // Set the URL to the Licensing Gateway Service. if (!PdfTools_Sdk_SetLicensingService("http://my.gateway.com:9999")) { // Handle error return 1; } // Set and check license key. If the license key is not valid, the function returns FALSE. if (!PdfTools_Sdk_Initialize("$LicenseKey$", NULL)) { // Handle error return 1; } ``` **Java:** ```java public static void main(String[] args) { try { // Set the URL to the Licensing Gateway Service. Sdk.setLicensingService(new java.net.URI("http://my.gateway.com:9999")); // Set and check license key. If the license key is not valid, an exception is thrown. Sdk.initialize("$LicenseKey$"); ``` **.NET:** ```csharp static void Main(string[] args) { try { // Set the URL to the Licensing Gateway Service. Sdk.LicensingService = new Uri("http://my.gateway.com:9999"); // Set and check license key. If the license key is not valid, an exception is thrown. Sdk.Initialize("$LicenseKey$"); ``` **Python:** ```python from pdftools_sdk.sdk import Sdk try: # Set the URL to the Licensing Gateway Service. Sdk.set_licensing_service("http://my.gateway.com:9999") # Set and check license key. If the license key is not valid, an exception is raised. Sdk.initialize("$LicenseKey$") ``` **note: More information about the `LicensingService` property is available in the SDK API references for [C](https://api-reference.pdf-tools.com/pdfsdk/latest/cdoc/_pdf_tools___pdf_tools_8h.html#aae4c0b5392a85912ca980bc75ce19163), [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.3/dotnet/html/P_PdfTools_Sdk_LicensingService.htm), [Java](https://api-reference.pdf-tools.com/pdfsdk/1.3/javadoc/com/pdftools/Sdk.html#setLicensingService(java.net.URI)), and [Python](https://api-reference.pdf-tools.com/pdfsdk/latest/python/pdftools_sdk.sdk.html#pdftools_sdk.sdk.Sdk.set_licensing_service).** ## Check the license status To review the remaining page credits, license expiration, and license validity in general, use one of the following approaches: - In the [Pdftools Portal](https://portal.pdf-tools.com/). For more information, review [View page credits consumption in the Pdftools Portal](#view-page-credits-consumption-in-the-pdftools-portal). - To check the license status programmatically, refer to [Check the license status programmatically](#check-the-license-status-programmatically). ### View page credits consumption in the Pdftools Portal 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. In the **Products** tab, click **See product** next to the Pdftools SDK entry. 1. Find your page credits usage in a specific section that lists your license key. On this page, you can review your total number of page credits, number of used credits, license key expiration, and more. ### Check the license status programmatically When the Pdftools SDK is successfully initialized, check your license status by accessing the `LicenseInfoSnapshot` property of the `SDK` class. This property provides the following information about the current license: - `IsValid`: License validity. - `ExpirationDate`: The date and time when the license expires. - `RemainingPages`: The number of pages available for processing based on the license agreement. - `Overconsumption`: The number of pages available for processing before the SDK stops functioning. If the `RemainingPages` value reaches zero, the Pdftools SDK provides a limited number of `Overconsumption` pages. The `Overconsumption` pages provide you with the opportunity to update your license agreement without disrupting your business processes. **caution: If both the `RemainingPages` and `Overconsumption` values reach zero, the Pdftools SDK stops functioning until the licensing service is updated with new license information.** **note: More information about the `LicenseInfoSnapshot` property is available in the Pdftools SDK API references for [C](https://api-reference.pdf-tools.com/pdfsdk/latest/cdoc/_pdf_tools___pdf_tools_8h.html#ab057d56c540312d05b9cc58172b59b15), [Java](https://api-reference.pdf-tools.com/pdfsdk/latest/javadoc/com/pdftools/Sdk.html#getLicenseInfoSnapshot()), [.NET](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Sdk_LicenseInfoSnapshot.htm), and [Python](https://api-reference.pdf-tools.com/pdfsdk/latest/pydocs/_autosummary/pdftools_sdk.sdk.html#pdftools_sdk.sdk.Sdk.get_license_info_snapshot).** ## Configure proxy Configure proxy settings when you need all your HTTPS and HTTP communication to go through one central point in your network. If your implementation of the Pdftools SDK requires connectivity to services external to your network that are not directly reachable by your application (for example, time-stamp authority (TSA), or you are using page credit license key with configured LGS), or the SDK is operating in an environment where direct internet access is restricted, such as behind a firewall. **Configure proxy if**: - You have a central point in your network through which you wire all your HTTPS and HTTP communication. - If you have a page credit license key and a central point in your network through which you wire all your HTTPS and HTTP communication. | **Condition** | **Proxy Required?** | **Notes** | | ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------ | | All HTTPS/HTTP communication must go through a central network point | Yes | General requirement when routing traffic through a proxy. | | SDK must connect to external services not directly reachable (for example, TSA, LGS) | Yes | Includes scenarios behind firewalls or restrictive environments. | | Page credit-based license key **and** centralized HTTPS/HTTP routing | Yes | LGS or credit license usage behind a proxy requires configuration. | | Trial license key in use | No | Proxy isn't required even if centralized routing exists. | | Page credit-based license key **without** the need for centralized HTTPS/HTTP routing | No | Proxy isn't required if the app can directly access the internet. | For specific steps to enable the proxy server, review the following resources depending on your use case: - Digital signing proxy configuration, review [Use a proxy server](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing/#use-a-proxy-server). - For other use cases, review the following [Procedure](#procedure). ### Procedure To configure a proxy, assign the `PdfTools.Sdk` class a `Proxy` server URI that the SDK will use for all HTTP and HTTPS communications with remote services. Follow these steps to configure a proxy: 1. In your application code, set the proxy before initializing the SDK: http[s]://[USER[:PASSWORD]@]HOST[:PORT] Where: - `http`/`https`: Protocol for connection to proxy. - `USER:PASSWORD` (optional): Credentials for connection to proxy (basic authorization). - `HOST`: Hostname of proxy. - `PORT`: Port for connection to proxy. For example, in C#: ```csharp Sdk.Proxy = new Uri("https://myuser:mypassword@proxy.example.com:8080"); ``` 1. **After** setting the proxy configuration, initialize the SDK using your license key. It is important to call the initialization **after** the proxy configuration. For more information about the Pdftools SDK initialization, review [Initialize the Pdftools SDK license](#initialize-the-pdftools-sdk-license). In the Pdftools SDK Shell Tool, you can configure the proxy using the `-proxy URL` option. In this option, replace the `URL` with your actual proxy URL. :::note[Notes] - You can also find information about the proxy configuration in the API references, for example [Sdk.Proxy Property](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Sdk_Proxy.htm) in the .NET API documentation. --- ## AI Smart Redact licensing AI Smart Redact supports two license validation modes: offline and runtime. Offline keys embed the expiration date and validate locally with no internet connection required. Runtime keys validate online against the Pdftools Licensing Service. :::info[Product documentation] For information about using AI Smart Redact, see [AI Smart Redact documentation](https://www.pdf-tools.com/docs/smart-redact/). :::info[Non-blocking licensing] AI Smart Redact licensing is non-blocking. The service never stops processing if you exceed the contractual page volume. Licensing depends solely on the license key expiration date. ## Get a license To get a license key or discuss pricing, [contact sales](https://www.pdf-tools.com/contact/). AI Smart Redact license keys have the following format: ``` ``` ## Find your license key To find and copy your AI Smart Redact license key: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, find AI Smart Redact and open the product details. 1. Copy the license key. ## Configure offline license key validation AI Smart Redact uses a single license key across the Manager, Worker, and Orchestrator services. Set the `PDFTOOLS_LICENSE_KEY` environment variable to apply the key. For end-to-end deployment instructions, see [Getting started](https://www.pdf-tools.com/docs/smart-redact/getting-started/). Page consumption tracking with an offline key is self-reported and optional. ## Other validation methods AI Smart Redact also supports runtime validation (online validation against the Pdftools Licensing Service) and the Licensing Gateway Service (LGS), which routes validation through a locally hosted gateway. For setup instructions, see [Licensing Service configuration](https://www.pdf-tools.com/docs/licenses/configure/). --- ## Toolbox add-on license management Learn how to manage the Toolbox add-on license keys. The information on this page applies to page credit licenses. :::info[Product documentation] For information about using the Toolbox add-on, review [Toolbox add-on documentation](https://www.pdf-tools.com/docs/toolbox-add-on/). ## Request a license The Toolbox add-on requires a trial or full license key. Review the following sections to acquire a [trial license](#trial-license) or a [full license](#full-license). ## Trial license To try out and evaluate the Toolbox add-on, you can acquire a trial license key for free when you sign up or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). For the exact procedure, review [Find the license key](#find-the-license-key) section. ### Trial license overview You can use the same license key for the Pdftools SDK, Pdftools Shell Tool, and Toolbox add-on. The Pdftools SDK and Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. ## Full license To request a full production license key: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Click **Contact sales** button. 1. Fill in the required details. 1. Click **Submit**. ## Find the license key To find and copy a license key: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Toolbox add-on, click **Get started** or **See product**. 1. Find your license key in the **License keys** section, and then click **Copy **. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs. ## Licensing credit count The Toolbox add-on checks page credit consumption and license validity only during specific operations. It consumes page credits based on: - Adding pages to a document (`PageList` mutations). - Accessing page content (`Page.Content` getters). Each time you add a page to a `PageList` or retrieve page content, **one page credit** is consumed. As a result, creating pages, setting metadata, and adding text or images to a page before adding it to the document does **not** consume page credits. ### Page mutations Adding pages to a `PageList` consumes credits in : - **Java**: `PageList.add*` methods - **Python**: `PageList.insert`, `PageList.append`, `PageList.extend` methods - **.NET**: `Document.Add*` methods, `CopyTo*` methods - **C**: `PtxPdf_PageList_Add*` functions ### Content getters Accessing page content consumes credits: - **Java**: `Page.getContent` method - **Python**: `Page.content` property - **.NET**: `Page.Content` property - **C**: `PtxPdf_Page_GetContent` function ### Calculating credits To determine how many page credits you'll need for your tasks using the Toolbox add-on, count the number of page additions and content retrievals. The **key principles** can be described as follows: - Each page addition to a `PageList` requires **1 page credit** - Each call to a content getter requires **1 page credit** - Copying pages without adding them to a `PageList` requires **0 page credits** - Multiple calls to content getters on the same page require **multiple page credits** For example: - **Copy 5 pages**: Opening a 10-page PDF, creating a new empty PDF, and copying 5 pages to it requires **5 page credits** (5 page additions, no `Page.Content` getter calls). - **Copy from multiple sources**: Opening two PDFs (10 pages and 12 pages), and copying 5 pages from each PDF into a new PDF requires **10 page credits** (10 page additions, no `Page.Content` getter calls). - **Extract text from 5 pages**: Opening a 10-page PDF and extracting text from 5 pages requires **5 page credits** (5 `Page.Content` getter calls). - **Create and add 5 pages**: Creating a new PDF, generating 10 pages with text and images, but only adding 5 pages to the document requires **5 page credits** (5 page additions, no `Page.Content` getter calls). - **Multiple content retrievals**: Opening a 1-page PDF and analyzing the text in 5 different stages, each calling the `Page.Content` getter, requires **5 page credits** (5 `Page.Content` getter calls on the same page). :::tip[Best practice] Avoid repeated calls to `Page.Content` getters. To minimize page credit consumption, cache the page content if you need to access it multiple times. ## License key validation License keys are validated using the [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/). The Toolbox add-on connects to the Pdftools Licensing Service to provide usage information and retrieve new licensing parameters after processing a document. The Pdftools Licensing Service collects the following statistics and information: - License key number. - The Toolbox add-on functions used and the number of pages processed. :::info[Privacy] Pdftools does **not** receive information about documents and data processed by the Toolbox add-on. At Pdftools, we highly value our customers' privacy. For information on managing your license key with the Pdftools Licensing Service, see [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/). ### The Toolbox add-on validation stages The Toolbox add-on validates the license key at different stages during operation: **Initial validation**: The validity of the license key is checked when you call the initialization method: - **C**: `Ptx_Sdk_Initialize` - **.NET**: `Sdk.Initialize` - **Python**: `Sdk.initialize` - **Java**: `Sdk.initialize` **Continued validation**: The license key validity is checked again when you use document operation methods: - **C**: `PtxPdf_Document_Create`, `PtxPdf_Document_Open`, `PtxPdf_PageList_Add*`, `PtxPdf_Page_GetContent` - **.NET**: `Document.Create`, `Document.Open`, `Document.Add*`, `CopyTo*`, `Page.Content property` - **Python**: `Document.create`, `Document.open`, `PageList.insert`, `PageList.append`, `PageList.extend`, `Page.content property` - **Java**: `Document.create`, `Document.open`, `PageList.add*`, `Page.getContent` This includes all page list mutations and content getters described in the [Licensing credit count](#licensing-credit-count) section. **caution: Without a valid license key, these operations fail. However, these methods only test whether the license key is valid. They do not test whether the license key still provides remaining page credits.** ## Initialize the Toolbox add-on license Learn how to use the Toolbox add-on license key. Review the appropriate link for your programming language: - [Initialize the Toolbox add-on in C](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-c#initialize-the-toolbox-add-on) - [Initialize the Toolbox add-on in Java](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-java#initialize-the-toolbox-add-on) - [Initialize the Toolbox add-on in .NET](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-dotnet#initialize-the-toolbox-add-on) ## Default license configuration By default, when the Toolbox add-on is initialized, it attempts to directly connect to the Pdftools Licensing Service. This requires an internet connection to the default licensing service URL: ``` https://licensing.pdf-tools.com/api/v1/licenses/ ``` **caution: By default, if the Toolbox add-on cannot connect to the licensing service URL, the SDK initialization fails.** ## Use the Licensing Gateway Use the [Licensing Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) (LGS) if the Toolbox add-on needs to operate without a direct connection to the Pdftools Licensing Service. To configure the SDK to use the Licensing Gateway Service, set the `LicensingService` property of the `Sdk` class before calling `Sdk.Initialize`. **C:** ```c int main(int argc, char* argv[]) { // Initialize the library Ptx_Initialize(); // Set the URL to the Licensing Gateway Service. if (!Ptx_Sdk_SetLicensingService("http://my.gateway.com:9999")) { // Handle error return 1; } // Set and check license key. If the license key is not valid, the function returns FALSE. if (!Ptx_Sdk_Initialize("$LicenseKey$", NULL)) { // Handle error return 1; } ``` **Java:** ```java public static void main(String[] args) { try { // Set the URL to the Licensing Gateway Service. Sdk.setLicensingService(new java.net.URI("http://my.gateway.com:9999")); // Set and check license key. If the license key is not valid, an exception is thrown. Sdk.initialize("$LicenseKey$", null); ``` **.NET:** ```csharp static void Main(string[] args) { try { // Set the URL to the Licensing Gateway Service. Sdk.LicensingService = new Uri("http://my.gateway.com:9999"); // Set and check license key. If the license key is not valid, an exception is thrown. Sdk.Initialize("$LicenseKey$", null); ``` **Python:** ```python from pdftools_toolbox import Sdk try: # Set the URL to the Licensing Gateway Service. Sdk.set_licensing_service("http://my.gateway.com:9999") # Set and check license key. If the license key is not valid, an exception is raised. Sdk.initialize("$LicenseKey$", None) ``` **note: More information about the `LicensingService` property is available in the Toolbox add-on API references for [C](https://api-reference.pdf-tools.com/pdfsdkxt/latest/cdoc/_pdf_tools___toolbox___ptx_8h.html#ac4591ca839d5e5e69af9e718b7b5f338), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/latest/javadoc/com/pdftools/toolbox/Sdk.html#setLicensingService(java.net.URI)), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/P_PdfTools_Toolbox_Sdk_LicensingService.htm), and [Python](https://api-reference.pdf-tools.com/pdfsdkxt/latest/pydocs/_autosummary/pdftools_toolbox.sdk.html#pdftools_toolbox.sdk.Sdk.set_licensing_service).** ## Check the license status To review the remaining page credits, license expiration, and license validity in general, use one of the following approaches: - In the [Pdftools Portal](https://portal.pdf-tools.com/). For more information, review [View page credits consumption in the Pdftools Portal](#view-page-credits-consumption-in-the-pdftools-portal). - If you need to review license usage programmatically, refer to [Workaround: Use the Pdftools SDK to check license status](#workaround-use-the-pdftools-sdk-to-check-license-status). ### View page credits consumption in the Pdftools Portal 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. In the **Products** tab, click **See product** next to the Toolbox add-on. 1. Find your page credits usage in a specific section that lists your license key. On this page, you can review your total number of page credits, number of used credits, license key expiration, and more. ### Workaround: Use the Pdftools SDK to check license status The Toolbox add-on doesn't provide a built-in license status check. However, the Pdftools SDK uses the same license key as the Toolbox add-on. As a workaround, you can use the Pdftools SDK to check your Toolbox add-on license usage programmatically. For more information, review [Check the license status](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license#check-the-license-status) in the Pdftools SDK licensing documentation and [Getting started with the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/). ## Configure proxy Configure proxy settings when you need all your HTTPS and HTTP communication to go through one central point in your network. If your implementation of the Toolbox add-on requires connectivity to services external to your network that are not directly reachable by your application (for example, you are using page credit license key with configured LGS), or the SDK is operating in an environment where direct internet access is restricted, such as behind a firewall. **Configure proxy if**: - You have a central point in your network through which you wire all your HTTPS and HTTP communication. - If you have a page credit license key and a central point in your network through which you wire all your HTTPS and HTTP communication. | **Condition** | **Proxy Required?** | **Notes** | | ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------ | | All HTTPS/HTTP communication must go through a central network point | Yes | General requirement when routing traffic through a proxy. | | SDK must connect to external services not directly reachable (for example, LGS) | Yes | Includes scenarios behind firewalls or restrictive environments. | | Page credit-based license key **and** centralized HTTPS/HTTP routing | Yes | LGS or credit license usage behind a proxy requires configuration. | | Trial license key in use | No | Proxy isn't required even if centralized routing exists. | | Page credit-based license key **without** the need for centralized HTTPS/HTTP routing | No | Proxy isn't required if the app can directly access the internet. | For specific steps to enable the proxy server, review the following [Procedure](#procedure). ### Procedure To configure a proxy, assign the `PdfTools.Toolbox.Sdk` class a `Proxy` server URI that the SDK will use for all HTTP and HTTPS communications with remote services. Follow these steps to configure a proxy: 1. In your application code, set the proxy before initializing the SDK: http[s]://[USER[:PASSWORD]@]HOST[:PORT] Where: - `http`/`https`: Protocol for connection to proxy. - `USER:PASSWORD` (optional): Credentials for connection to proxy (basic authorization). - `HOST`: Hostname of proxy. - `PORT`: Port for connection to proxy. For example, in C#: ```csharp Sdk.Proxy = new Uri("https://myuser:mypassword@proxy.example.com:8080"); ``` 1. **After** setting the proxy configuration, initialize the SDK using your license key. It is important to call the initialization **after** the proxy configuration. For more information about the Toolbox add-on SDK initialization, review [Initialize the Toolbox add-on license](#initialize-the-toolbox-add-on-license). In the Toolbox add-on SDK Shell Tool, you can configure the proxy using the `-proxy URL` option. In this option, replace the `URL` with your actual proxy URL. :::note[Notes] - You can also find information about the proxy configuration in the API references, for example [Sdk.Proxy Property](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/P_PdfTools_Toolbox_Sdk_Proxy.htm) in the .NET API documentation. --- ## PDF Viewer SDK licensing The PDF Viewer SDK differs in how you can use the license keys and initialize the SDK. Review [version 5](#version-5) and [version 4](#version-4) sections separately depending on which version you use. :::info[Product documentation] For information about using the PDF Viewer SDK, review [PDF Viewer SDK documentation](https://www.pdf-tools.com/docs/pdf-web-viewer/). ## Version 5 ### License overview The following table explains the pricing and feature offering available for various license types of the PDF Viewer SDK: No license Free view-only Trial Professional Business Enterprise How to No license key is need Contact sales Contact sales Contact sales Contact sales Contact sales Watermark Yes No No No No No Feature sets View-only View-only All Select one Select three All Domains - One On demand One Three On demand Maximum concurrent users 100 100 extensible 100 extensible 100 extensible 1,000 extensible Contract based ### License key The PDF Viewer SDK displays watermarked pages by default. Use a license key to remove the watermark for free. For more details, review [Manage license key](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#manage-license-key) section. ## Version 4 Without an active license the PDF Viewer SDK version 4 applies a watermark to the viewed PDFs. Try the PDF Viewer SDK for free. See the [product demo](https://www.pdf-tools.com/pdfwebviewer/) in action. Install PDF Viewer SDK locally from the [npmjs](https://www.npmjs.com/package/@pdftools/four-heights-pdf-web-viewer) website. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license and remove the watermark. Review how to enter the license key in the [Basic usage](https://www.pdf-tools.com/docs/pdf-web-viewer/4/getting-started/#basic-usage) documentation. ### Troubleshooting The following sections can help you to fix specific issues related to the PDF Viewer SDK licensing. #### License key cannot be set If the license key cannot be set, the call to the `PdfWebViewer` constructor results in an error. ##### Possible causes - There is a typographic error in the license key. - When the key was copied, the operation altered the characters in the key, such as commas. - The key has a wrong format. - The key belongs to a different product. - The key is an evaluation license key that expired. ##### Solution Make sure the key is issued for the PDF Viewer and has the following format: ``` <4H,V4,VIEWWEB,XXXXXXXXXXXXXXXXXXXX> ``` If an evaluation license key has expired and you want to extend the period of evaluation, use the [Contact page](https://www.pdf-tools.com/contact/) to request a new evaluation license key. #### License check fails at runtime In this case, the license can be set and the call to the constructor `PdfWebViewer` is successful. However, when opening a PDF file, you are prompted with message: "The current license does not permit running the product on this domain." ##### Possible causes - The license key is not meant to be used with the current domain. ##### Solution Ensure that the domain on which the PDF Viewer is running matches the domain to which the license key is registered. --- ## Pdftools OCR Service The OCR Service enables optical character recognition (OCR) to extract text from images and scanned documents, transforming them into searchable and editable PDF documents. You can use the Pdftools OCR Service in two ways: - **With the Conversion Service**: Configure OCR as a processing step in the Conversion Service on Windows Server or in Docker. Refer to [Getting started](https://www.pdf-tools.com/docs/ocr-service/getting-started/). - **With the Pdftools SDK**: Use the built-in OCR module to process PDFs programmatically in .NET, Java, Python, or C. Refer to [OCR with the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/). ## Key features - Embeds the recognized text in Unicode format into PDF or PDF/A files. - Supports over 180 natural and technical languages. - Provides an OCR service mode for shared use across multiple platforms. - Predefined and custom OCR profiles to optimize for accuracy or performance. - Automatic skew correction, rotation, and resolution handling. - Detection of tables, barcodes, engineering drawings, and other complex layout elements. ## System architecture The Pdftools OCR Service comprises two .NET Core applications, both running on Kestrel servers: - **Manager node**: This node handles HTTP requests and dispatches jobs to available workers. - **Worker node**: Performs the OCR processing. This node handles OCR processing and remains the most resource-intensive component. This separation allows for flexible deployment and scaling, where a single manager can coordinate multiple workers. For more information, review [Scale the Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/guides/scale). ## System requirements ### Worker nodes These nodes run the OCR engine and require more processing power and memory. The worker node recommended hardware setup is: - Windows 8 or newer (x64) or Linux (Docker) - 8 GB RAM or more - Quad-core CPU or better - SSD with at least 4 GB free space ### Manager nodes These nodes coordinate OCR jobs and handle requests, with significantly lower system requirements. The manager node recommended hardware setup is: - Windows 8 or newer (x64) or Linux (Docker) - 4 GB RAM - Quad-core CPU - SSD storage ### For standalone installations You can also install the manager and the worker on the same machine. The requirements allocated for [Worker nodes](#worker-nodes) suffice. ## Licensing The Pdftools OCR Service requires a license key to operate. You can use one of two license key types: - Trial license key - Full license key For information about configuring license keys, review [Get started with OCR in the Conversion Service](https://www.pdf-tools.com/docs/ocr-service/getting-started/). For offline licensing options, review [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/). --- --- ## Get started with the Pdftools OCR Service Pdftools OCR Service extracts text from images and scanned documents using optical character recognition (OCR). Get started with one of the following guides: --- --- ## OCR Service in Docker Learn how to run the Pdftools OCR Service in Docker. ## Get a license key To get an evaluation or full license key, follow these steps: 1. Fill in the [Pdftools contact form](https://www.pdf-tools.com/contact/) and mention that you want to evaluate or use the Pdftools OCR Service. 1. After you receive confirmation, sign up or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Click **See product** next to the Pdftools OCR Service and copy your license key. ## Prerequisites - You have **Docker Compose** installed to run the Pdftools OCR Service in Docker. - You have a valid **Pdftools OCR Service license key**. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/) to retrieve your license key. ## Run Pdftools OCR Service in Docker Pdftools OCR Service consists of two containers: the **Manager** and the **Worker**. You need both for a functional deployment. To run the Pdftools OCR Service in Docker, follow these steps: 1. Create a file named `docker-compose.yaml` and insert the following code: ```yaml services: manager: image: pdftoolsag/ocr-service-manager:IMAGE_VERSION ports: - "7982:8080" environment: - ServiceCommunication__ServiceCommunicationType=Rest - ServiceCommunication__ConnectionString=http://worker:8080 - PortNumber=8080 volumes: - pdftools-data:/var/lib/pdftools - pdftools-db:/usr/share/Pdftools - pdftools-logs:/var/log/pdftools worker: image: pdftoolsag/ocr-service-worker:IMAGE_VERSION shm_size: "2gb" ports: - "7998:8080" environment: - Licensing__LicenseKey=LICENSE_KEY_VALUE - PortNumber=8080 volumes: - pdftools-data:/var/lib/pdftools - pdftools-logs:/var/log/pdftools volumes: pdftools-data: pdftools-db: pdftools-logs: ``` Replace the following placeholders with specific values: - `IMAGE_VERSION`: The Pdftools OCR Service version number. For example: `1.1.0`, `1.1`, `1` - `LICENSE_KEY_VALUE`: Pass the license key value. Use the license key in the same format as you copied it. Include the less-than (`<`) and greater-than (`>`) signs. 1. In the directory where you created the `docker-compose.yaml`, run the following command: ```bash docker compose up -d ``` 1. Verify both containers are running: ```bash docker compose ps ``` 1. Check that the worker has loaded the OCR engine successfully: ```bash docker compose logs worker ``` Look for the message **Engine loaded** in the log output to confirm the OCR engine is ready. **tip: In its default configuration, the Pdftools OCR Service requires a network connection to validate the license key. For information about partially offline or fully offline solutions, review [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/).** ## Environment variables Learn about additional configuration of the Pdftools OCR Service Docker containers. Use the variables in the `environment` section of worker and manager nodes in the `docker-compose.yaml`. ### Manager environment variables | Variable | Default value | Description | |--------------------------------------------------|-------------------------------------|--------------------------------------------------------------| | `ServiceCommunication__ServiceCommunicationType` | `Rest` | Communication protocol with the worker | | `ServiceCommunication__ConnectionString` | — | Worker connection string (for example, `http://worker:8080`) | | `Database__DatabaseType` | `SqlLite` | Database backend (`SqlLite`, `PostgreSql`) | | `Database__DeleteJobsAfterDays` | `2` | Days before completed jobs are automatically deleted | | `FileStorage__FileStorageType` | `HostFileSystem` | Storage backend (`HostFileSystem`, `MinIO`) | | `FileStorage__FilesDirectoryPath` | `/var/lib/pdftools/files` | Path for file storage | | `FileStorage__DeleteFilesAfterDays` | `2` | Days before files are automatically deleted | | `MaxRequestBodySizeBytes` | `104857600` | Maximum upload size in bytes (default 100 MB) | | `PortNumber` | `8080` | Internal listening port | | `LogFilePath` | `/var/log/pdftools/manager-log.txt` | Log file location | | `LogRetentionDays` | `7` | Number of days to retain log files | ### Worker environment variables | Variable | Default value | Description | |--------------------------------------------------|------------------------------------|----------------------------------------------------------------------------| | `Licensing__LicenseKey` | — | **Required.** Your Pdftools OCR license key | | `Licensing__LgsURL` | — | License Gateway Service URL for offline licensing | | `FileStorage__FileStorageType` | `HostFileSystem` | Storage backend (`HostFileSystem`, `MinIO`) | | `FileStorage__FilesDirectoryPath` | `/var/lib/pdftools/files` | Path for file storage | | `ServiceCommunication__ServiceCommunicationType` | `Rest` | Communication protocol with the manager (`Rest`, `RabbitMQ`, `PostgreSql`) | | `PortNumber` | `8080` | Internal listening port | | `LogFilePath` | `/var/log/pdftools/worker-log.txt` | Log file location | | `LogRetentionDays` | `7` | Number of days to retain log files | :::info[Worker requirements] The worker requires at least 2 GB of shared memory (`shm_size: "2gb"`) for the OCR engine. ## Set up Pdftools OCR Service with Conversion Service Configure an OCR-enabled Conversion Service profile to use Pdftools OCR Service for text recognition. If you run Conversion Service on Windows, the profile takes effect immediately after you apply it. If you run Conversion Service in Docker, you also need to export the profile and import it into the Docker container. ### Configure an OCR profile Before you begin: - You have a Windows machine with Conversion Service installed. This machine doesn't need to be your production environment. To enable OCR in a Conversion Service profile: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. OCR is available in **Archive** and **Conversion** workflows. 1. Enable the **OCR Settings** toggle. 1. In the **OCR Settings** section, click **Add Item**. 1. Select **Pdftools OCR Service (3H Legacy Compatible)** as the OCR engine, and then click **Next**. 1. Optional: If Pdftools OCR Service runs on a different host, update the **Service URL** to point to your Pdftools OCR Service instance (for example, `http://OCR_MANAGER_HOST:7982`). :::tip If Conversion Service also runs in Docker, `localhost` doesn't resolve to the host machine. Refer to [Docker networking](#docker-networking) for alternatives. ::: 1. Click **Apply**. For advanced settings such as recognition languages and predefined profiles, refer to [Configure OCR in the Conversion Service](https://www.pdf-tools.com/docs/ocr-service/getting-started/windows/set-up-with-conversion-service#configure-ocr-in-the-conversion-service). ### Docker networking The default Service URL `http://localhost:7982` works when Conversion Service runs directly on the host machine. When Conversion Service also runs in Docker, `localhost` resolves to the Conversion Service container itself, not the host. Use one of the following approaches depending on your setup: - **Same Docker Compose file**: Add the OCR Service containers to the same `docker-compose.yaml` as Conversion Service and use the Manager's service name as the hostname (for example, `http://manager:8080`). Docker Compose creates a shared network automatically. Use the internal port (`8080`), not the published host port (`7982`). - **Separate Docker Compose files**: Create a shared Docker network and attach both Compose projects to it. Then reference the Manager by its service name. - **Host networking** (Docker Desktop on Windows and macOS): Use `http://host.docker.internal:7982` to reach the OCR Manager through the host's published port. ### Export the profile If you run Conversion Service in Docker, export the configured profile so you can import it into the Docker container: 1. In the Configurator, click **Save & Restart Service**. 1. On the **Workflows & Profiles** page, click the **vertical three-dot menu**, and then click **Export Profiles**. 1. Select the profile you want to export, or click **Select All** to export all profiles. 1. Click **Export**, and then select the file destination. ### Run Conversion Service in Docker To set up Conversion Service as a Docker container, refer to [Configure containers using Docker Compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose). ### Import the profile into Docker Compose To import the exported profile into the Conversion Service Docker container, refer to [Import profiles using Docker Compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker/#import-profiles-using-docker-compose). --- --- ## Get started with Pdftools OCR Service on Windows Learn how to set up Pdftools OCR Service on Windows with Conversion Service or with Pdftools SDK. Pick the path that matches your use case: --- --- ## Set up Pdftools OCR Service with Conversion Service Learn how to install the Pdftools OCR Service on Windows, and then enable and configure it in the Conversion Service. ## Get a license key To get an evaluation or full license key and download the Pdftools OCR Service installer, follow these steps: 1. Fill in the [Pdftools contact form](https://www.pdf-tools.com/contact/) and mention that you want to evaluate or use the Pdftools OCR Service. 1. After you receive confirmation, sign up or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Click **See product** next to the Pdftools OCR Service, download the MSI installer, and copy your license key. ## Install Pdftools OCR Service To install the Pdftools OCR Service, follow these steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the **Products**, find the **Pdftools OCR Service**, and then click **Get started** or **See product**. 1. In the **Product builds** section, find the `ocr-service-VERSION_NUMBER.msi` package, and then click **Download **. 1. Follow the instructions in the installer. 1. In the [Pdftools Portal](https://portal.pdf-tools.com/), on the **Products** page, next to the Pdftools OCR Service, click **Get started** or **See product**. 1. Next to the **Pdftools OCR Service** license key, click **Click to copy **. 1. Go to the installation folder of your **worker** nodes and open the `appsettings.json`. Full path example: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` 1. Replace the `""` placeholder with your license key, and then save the file. :::tip In its default configuration, the Pdftools OCR Service requires a network connection to validate the license key. For information about a partially offline or a fully offline solution, review [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/). ::: 1. Open the Windows start menu and search for **Services**, and then search for **Pdftools OCR Service Worker**. Right-click the entry and click **Start** to start the service. 1. Optional: Check the log files to verify that the installation succeeded. Example path to the `worker-logYYYYMMDD.txt` file: ``` C:\ProgramData\Pdftools\OcrService\logs\worker-log20251007.txt ``` An entry similar to the following at the end of the log file indicates a successful installation: ``` 2026-04-15 15:07:04.561 +02:00 [Information] Application started. Hosting environment: "Production"; Content root path: "C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker" ``` To replace a trial license key or insert a different key, repeat the procedure from step 7. ## Enable Pdftools OCR Service in the Conversion Service The following steps explain how to enable and configure OCR in the Conversion Service profile: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. The OCR is available in **Archive** and **Conversion** workflows. 1. Enable the **OCR Settings** toggle. 1. In the **OCR Settings** section, click the **Add Item** button. 1. Select **Pdftools OCR Service (3H Legacy Compatible)** as the OCR engine, and then click **Next**. 1. Optional: If the OCR service is on a different server, update the **Service URL**. 1. Click **Apply**. Pdftools OCR Service must be configured and accessible through HTTP. You can configure multiple Pdftools OCR Service instances to distribute OCR processing. For more details, review [Scale the Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/guides/scale). ## Configure OCR in the Conversion Service You can configure parameters such as recognition languages, predefined profiles, and text extraction accuracy. To edit the configuration, follow these steps: 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. 1. Navigate to the **OCR Settings** section. 1. Next to **Engine**, click the pen icon in the **Pdftools OCR Service (3H Legacy Compatible)** section. 1. After editing your configuration, click **Apply**. You can edit parameters in the **Parameters** and **Languages** input fields: - In the **Parameters** input field, the key-value pairs are joined by an equal sign and separated by semicolons (`;`). For more information about available parameters, review [Parameters](https://www.pdf-tools.com/docs/ocr-service/references/parameters/). - The default parameter set in the Conversion Service Configurator: ``` PredefinedProfile=DocumentConversion_Accuracy ``` - An example of more parameters set in the Conversion Service Configurator: ``` PredefinedProfile=DocumentArchiving_Accuracy;PreprocessingOnly=false;RemoveGarbage=0;RecognizeBlankPages=false;BlankPageMargin=0.02;DisableMaskEmbedding=false ``` - In the **Languages** input field, you can set the languages that the OCR recognizes as one comma-separated string. For more information about available language recognition options, review [Supported languages](https://www.pdf-tools.com/docs/ocr-service/references/ocr-languages). - Default OCR language configuration in the Conversion Service Configurator: ``` English,German,French ``` - An example of more natural and technical languages separated by commas: ``` English,German,French,Tagalog,Corsican,Spanish,Chemistry,Java ``` :::tip[References] For more information about specific configuration options, review [Pdftools OCR Service references](https://www.pdf-tools.com/docs/ocr-service/references/). --- ## Set up Pdftools OCR Service with Pdftools SDK Install the Pdftools OCR Service on Windows, and then use the Pdftools SDK to apply OCR to a PDF through the running service. ## Get a license key To try or buy the Pdftools OCR Service, follow these steps: 1. Fill in the [Pdftools contact form](https://www.pdf-tools.com/contact/) and mention that you want to evaluate or use the Pdftools OCR Service. 1. After you receive confirmation, sign up or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Click **See product** next to the Pdftools OCR Service, download the MSI installer, and copy your license key. ## Install Pdftools OCR Service To install the Pdftools OCR Service, follow these steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Go to the **Products**, find the **Pdftools OCR Service**, and then click **Get started** or **See product**. 1. In the **Product builds** section, find the `ocr-service-VERSION_NUMBER.msi` package, and then click **Download **. 1. Follow the instructions in the installer. 1. In the [Pdftools Portal](https://portal.pdf-tools.com/), on the **Products** page, next to the Pdftools OCR Service, click **Get started** or **See product**. 1. Next to the **Pdftools OCR Service** license key, click **Click to copy **. 1. Go to the installation folder of your **worker** nodes and open the `appsettings.json`. Full path example: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` 1. Replace the `""` placeholder with your license key, and then save the file. :::tip In its default configuration, the Pdftools OCR Service requires a network connection to validate the license key. For information about a partially offline or a fully offline solution, review [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/). ::: 1. Open the Windows start menu and search for **Services**, and then search for **Pdftools OCR Service Worker**. Right-click the entry and click **Start** to start the service. 1. Optional: Check the log files to verify that the installation succeeded. Example path to the `worker-logYYYYMMDD.txt` file: ``` C:\ProgramData\Pdftools\OcrService\logs\worker-log20251007.txt ``` An entry similar to the following at the end of the log file indicates a successful installation: ``` 2026-04-15 15:07:04.561 +02:00 [Information] Application started. Hosting environment: "Production"; Content root path: "C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker" ``` To replace a trial license key or insert a different key, repeat the procedure from step 7. ## Run the OcrDocument sample With the Pdftools OCR Service running, use the Pdftools SDK to apply OCR to a PDF. The `OcrDocument` sample takes four arguments: ``` OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH ``` - `OCR_ENGINE_NAME`: Set to `service` to route OCR through the Pdftools OCR Service. - `LANGUAGE`: The OCR recognition language, for example, `English`. For more options, review [Supported languages](https://www.pdf-tools.com/docs/ocr-service/references/ocr-languages). - `INPUT_PATH`: Path to the PDF to apply OCR to. - `OUTPUT_PATH`: Path to the generated PDF. Each `OcrDocument` sample repository includes a test file named `InvoiceNone.pdf` that you can use to verify your setup. ### C# **Prerequisites**: .NET 8 SDK. 1. Clone the **[sdk-examples-csharp](https://github.com/pdf-tools/sdk-examples-csharp)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-csharp.git ``` 1. Navigate to the `OcrDocument` sample: ```bash cd sdk-examples-csharp/OcrDocument ``` 1. Apply OCR to the included test file `InvoiceNone.pdf`: ```bash dotnet run --framework net8.0 --project PdfToolsOcrDocument.csproj service English InvoiceNone.pdf InvoiceOcr.pdf ``` Compare the command with placeholders: ```bash dotnet run --framework net8.0 --project PdfToolsOcrDocument.csproj OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH ``` ### Java **Prerequisites**: Java Development Kit (JDK) 8 or later. Switch between the following tabs to display steps for Maven, Gradle, or Manual build. **Maven:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Navigate to the `OcrDocument` sample: ```bash cd sdk-examples-java/OcrDocument ``` 1. Build the project and apply OCR to the included test file `InvoiceNone.pdf`: ```powershell mvn clean install mvn exec:java '-Dexec.mainClass=PdfToolsOcrDocument.PdfToolsOcrDocument' '-Dexec.args=service English InvoiceNone.pdf InvoiceOcr.pdf' ``` :::note Wrap both `-D` arguments in single quotes. PowerShell passes the arguments literally this way; double quotes are re-interpreted by PowerShell and the command fails. The single-quote form also works in Bash and zsh. ::: Compare the command with placeholders: ```powershell mvn exec:java '-Dexec.mainClass=PdfToolsOcrDocument.PdfToolsOcrDocument' '-Dexec.args=OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH' ``` **Gradle:** The sample doesn't ship a Gradle wrapper, so install Gradle locally or generate a wrapper with `gradle wrapper`. 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Navigate to the `OcrDocument` sample: ```bash cd sdk-examples-java/OcrDocument ``` 1. Build the project and apply OCR to the included test file `InvoiceNone.pdf`: ```powershell gradle build gradle run --args="service English C:\INPUT_DIR\InvoiceNone.pdf C:\OUTPUT_DIR\InvoiceOcr.pdf" ``` Replace the following placeholders with specific values: - `C:\INPUT_DIR`: Absolute path to the folder containing your input PDF. For the sample verification, use the folder where you cloned `sdk-examples-java/OcrDocument`. - `C:\OUTPUT_DIR`: Absolute path to the folder where the generated PDF should be written. :::note Use absolute paths for the input and output files. `gradle run` sets the working directory to the subproject folder (`lib/`), so relative paths resolve there rather than where you invoked Gradle. ::: Compare the command with placeholders: ```powershell gradle run --args="OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH" ``` **Manual:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Navigate to the `OcrDocument` sample: ```bash cd sdk-examples-java/OcrDocument ``` 1. Download [`pdftools-sdk-1.16.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.16.0/pdftools-sdk-1.16.0.jar) and [`pdftools-sdk-native-1.16.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk-native/1.16.0/pdftools-sdk-native-1.16.0.jar) from Maven Central. Save both JARs into any folder. The following commands refer to that folder as `C:\JAR_DIR`. 1. Compile the sample: ```powershell javac -cp "C:\JAR_DIR\pdftools-sdk-1.16.0.jar" -d out lib/src/main/java/PdfToolsOcrDocument/PdfToolsOcrDocument.java ``` Replace `C:\JAR_DIR` with the absolute path to the folder where you saved the two JAR files. 1. Apply OCR to the included test file `InvoiceNone.pdf`: ```powershell java -cp "out;C:\JAR_DIR\pdftools-sdk-1.16.0.jar;C:\JAR_DIR\pdftools-sdk-native-1.16.0.jar" PdfToolsOcrDocument.PdfToolsOcrDocument service English InvoiceNone.pdf InvoiceOcr.pdf ``` Replace `C:\JAR_DIR` in both classpath entries with the same folder path you used for the compile step. :::note On macOS or Linux, use `:` instead of `;` as the classpath separator. ::: Compare the command with placeholders: ```powershell java -cp "out;C:\JAR_DIR\pdftools-sdk-1.16.0.jar;C:\JAR_DIR\pdftools-sdk-native-1.16.0.jar" PdfToolsOcrDocument.PdfToolsOcrDocument OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH ``` ### Python **Prerequisites**: Python 3.7 or later. 1. Clone the **[sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-python.git ``` 1. Navigate to the `OcrDocument` sample: ```bash cd sdk-examples-python/OcrDocument ``` 1. Install the Pdftools SDK package: ```bash pip install pdftools_sdk ``` 1. Apply OCR to the included test file `InvoiceNone.pdf`: ```bash python ./ocr_document.py service English InvoiceNone.pdf InvoiceOcr.pdf ``` :::note On systems where only Python 3 is installed and `python` isn't aliased, run `python3` instead. ::: Compare the command with placeholders: ```bash python ./ocr_document.py OCR_ENGINE_NAME LANGUAGE INPUT_PATH OUTPUT_PATH ``` ## Learn more For deeper OCR guidance with Pdftools SDK, including how to OCR documents programmatically and OCR best practices, review [Pdftools SDK OCR guides](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/), in Pdftools SDK documentation. --- ## Configure Learn how to upgrade to a new version, how to configure monitoring, how to scale the Pdftools OCR Service, and how to work with profiles. --- ## Monitor Pdftools OCR Service You can monitor the OCR service programmatically using health check endpoints exposed by both the **Manager** and **Worker** components. To check the readiness status, you can trigger these endpoints: - Manager: ```url http://localhost:7982/healthz/ready ``` - Worker: ```url http://localhost:7998/healthz/ready ``` Check **log files** to monitor the correct operation of the services. The path to the log files is configurable. Review [Default `appsettings.json`](#default-appsettingsjson) for an example of the configured path to a log file. ## Manager configuration overview The OCR Service Manager uses `appsettings.json` files to manage its configuration. The following example shows a configuration for the **Manager** component, which also shows how it interacts with **Workers**. The default path of the manager configuration file: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrService\appsettings.json ``` ### Default `appsettings.json` ```json { "Database": { "DatabaseType": "SqlLite", "DeleteJobsAfterDays": 2 }, "FileStorage": { "FileStorageType": "HostFileSystem", "FilesDirectoryPath": "C:/ProgramData/Pdftools/OcrService/Files", "DeleteFilesAfterDays": 2 }, "ServiceCommunication": { "ServiceCommunicationType": "Rest", "ConnectionString": "http://localhost:7998/" }, "PortNumber": 7982, "MaxRequestBodySizeBytes": 104857600, "LogFilePath": "C:/ProgramData/Pdftools/OcrService/logs/manager-log.txt", "LogRetentionDays": 7 } ``` - `Database` - `DatabaseType`: Database backend (for example `SqlLite` or `PostgreSql`). If you use `PostgreSql`, also add `ConnectionString`. - `ConnectionString`: Connection string for `PostgreSql`; omitted in the default settings because `SqlLite` doesn’t require a password. - `DeleteJobsAfterDays`: Number of days after which completed job records are removed. - `FileStorage` - `FileStorageType`: Storage backend (for example `HostFileSystem`). - `FilesDirectoryPath`: Directory that stores OCR-processed files. - `DeleteFilesAfterDays`: Number of days after which stored files are deleted. - `ServiceCommunication` - `ServiceCommunicationType`: Method the manager uses to reach worker nodes (currently `Rest`). - `ConnectionString`: Endpoint URL of the worker node or load balancer. - `MaxRequestBodySizeBytes`: Maximum number of bytes for the request size. Default is 104857600 bytes, approximately 100 MB. If necessary, increase this value for larger files. - `PortNumber`: Port that the manager listens on; the default is `7982`. - `LogFilePath`: Path to the log file. - `LogRetentionDays`: Number of days to retain log files. ## Worker configuration overview The OCR Service Worker uses `appsettings.json` files to manage its configuration. The following example shows a configuration for the **Worker** node. The following is the default path of the worker configuration file: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` ### Default `appsettings.json` ```json { "PortNumber": 7998, "LogFilePath": "C:/ProgramData/Pdftools/OcrService/logs/worker-log.txt", "LogRetentionDays": 7, "FileStorage": { "FileStorageType": "HostFileSystem", "FilesDirectoryPath": "C:/ProgramData/Pdftools/OcrService/Files" }, "ServiceCommunication": { "ServiceCommunicationType": "Rest" }, "Licensing": { "LicenseKey": "", "LgsURL": "http://localhost:9999" } } ``` - `PortNumber`: Port used by the worker node for incoming requests, **7998** is the default in this case. - `LogFilePath`: Path to the log file and the retention period for logs. - `LogRetentionDays`: Retention period for logs. - `FileStorage` - `FileStorageType`: Storage system type (for example `HostFileSystem`). - `FilesDirectoryPath`: Directory path for storing OCR-processed files. - `ServiceCommunication` - `ServiceCommunicationType`: Communication method that reaches the worker (currently `Rest`). - `Licensing` - `LicenseKey`: Your Pdftools product key. Provide the license key in every worker that you set up. - `LgsURL`: Your connection URL to the [Licensing Gateway Service (LGS)](https://www.pdf-tools.com/docs/licenses/configure/). An optional property. If you **don't** specify the `LgsURL`, the Pdftools OCR Service automatically connects to the Pdftools Licensing Service, requiring an internet connection. --- ## Work with profiles Pdftools OCR Service lets you fine-tune the OCR engine using various parameters. You can specify parameters for image preprocessing, analysis, recognition, and synthesis to obtain the optimal speed and quality of processing. ## Predefined profiles The Pdftools OCR Service lets you set predefined profiles designed for the main usage scenarios (the specifications of all predefined profiles are described in [PredefinedProfiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/#predefinedprofile) references). The settings provided in these profiles are best suited for their respective situations. Often, a profile comes in two versions: one optimized for the highest quality of the resulting document and the other optimized for the fastest processing speed. ## Custom profiles You can also create your own profile file. These profile files use INI file syntax. You can add comments in an INI file by starting a line with a semicolon (`;`). The sections contain the names of the objects whose properties can be specified. The keys contain the properties with their values. The special section called `UserData` can contain any user-defined keys. The values of Boolean properties are represented by the strings `true` or `false`, while enumeration properties are represented by corresponding constants, for example: ```ini [PagePreprocessingParams] DiscardColorImage = true [PDFExportParams] TextExportMode = PEM_ImageOnText ; This line is a comment [RecognizerParams] Mode = RM_Fast ``` The [`Profile`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/#profile) parameter lets you load a custom profile file. After this file is loaded, the created objects will have the new values specified in the file. Loading parameters from a profile is similar to specifying the corresponding properties in the code. If an empty string is passed to the `Profile` parameter, the standard default values will be used. The objects in the square brackets (for example, `[RecognizerParams]`) represent INI file sections. You may include various parameters only under certain INI file sections. For more details, review [Custom profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/). To configure a custom profile for specific OCR processing behavior, follow these steps: 1. Create a custom profile INI file. 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. 1. Navigate to the **OCR Settings** section. 1. Next to **Engine**, click the pen icon in the **Pdftools OCR Service (3H Legacy Compatible)** section. 1. In the **Parameters** input field, include a path to your INI file, for example: ```bash Profile="C:\ocr\profiles\document_conversion_high_accuracy.ini" ``` 1. After editing your configuration, click **Apply**. The INI file must be on the **same** machine as the **Pdftools OCR Service Manager** node. If both `Profile` and `PredefinedProfile` are set, the custom `Profile` **overrides** the predefined profile. ## Using both predefined and custom profiles You can load one predefined profile and one custom profile simultaneously. The custom profile has priority over the predefined profile. For example, if a custom profile sets the same parameter as a predefined profile, the value from the custom profile will be used. If you load one more predefined profile, this new profile replaces the previous predefined profile. Similarly, a new custom profile replaces the previous custom profile. --- ## Scale Pdftools OCR Service The Pdftools OCR service uses a **master-worker** architecture. The central **master** node, called the **Pdftools OCR Service Manager**, distributes tasks to multiple **worker** nodes, called **Pdftools OCR Service Workers**, which perform the actual processing. In the Pdftools OCR Service installer, you can set up **Pdftools OCR Service Manager** that communicates with a **Pdftools OCR Service Worker**. The following diagram illustrates this configuration: Learn how to scale the Pdftools OCR Service horizontally by configuring the manager to work with multiple worker nodes in this guide. ## Scaling worker nodes The manager node communicates with worker nodes through a RESTful API. In the scaled worker setup, you can create an architecture similar to the following: 1. Locate the manager configuration file. In a default installation, the file is located at: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrService\appsettings.json ``` 1. Point `ServiceCommunication` to your load balancer: ```json { "ServiceCommunication": { "ServiceCommunicationType": "Rest", "ConnectionString": "http://localhost:8080/" } } ``` 1. Install worker nodes on different host machines. You don't need to install the manager again. 1. Configure a load balancer to distribute requests to your worker nodes. 1. Locate the worker configuration file. In a default installation, the file is located at: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` 1. Add a license key to each worker node: ```json { "Licensing": { "LicenseKey": "" } } ``` In a default installation, the worker configuration file is located at: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrWorker\appsettings.json ``` 1. Share a common file storage between all manager and worker nodes: ```json { "FileStorage": { "FileStorageType": "HostFileSystem", "FilesDirectoryPath": "F:/SharedFolder/ProgramData/Pdftools/OcrService/Files" } } ``` - `FileStorage` - `FileStorageType`: Storage system type (for example, `HostFileSystem`). - `FilesDirectoryPath`: Directory path for storing OCR-processed files. 1. Make sure every **manager** and all **worker** nodes: - Uses the same `FileStorage` settings. - Has read and write permission for the shared directory. ## Scaling manager nodes You can scale the manager nodes similarly to the worker nodes. **info: Switch to **PostgreSQL** instead of SQLite to support horizontal scaling of manager nodes. The PostgreSQL database lets you share the state of multiple managers. For more information, review [Default appsettings.json](https://www.pdf-tools.com/docs/ocr-service/guides/monitor#default-appsettingsjson).** The following steps add to the previous section, where worker nodes were already scaled. 1. Locate the manager configuration file. In a default installation, the file is located at: ``` C:\Program Files\Pdftools\Pdftools OCR Service\PdftoolsOcrService\appsettings.json ``` 1. Configure **PostgreSQL**: ```json { "Database": { "DatabaseType": "PostgreSql", "ConnectionString" : "User ID=myUser;Password=mySecurePassword;Server=my.database.com;Port=5432;Database=ocr-service-db;", "DeleteJobsAfterDays": 2 } } ``` 1. Install manager nodes on separate hosts. 1. Configure a load balancer for the manager nodes. --- ## Update Pdftools OCR Service To update to a new version, follow these steps: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to the Pdftools OCR Service, click **Get started** or **See product**. 1. In the **Product builds** section, find the latest `ocr-service-VERSION_NUMBER.msi` package, and then click **Download **. 1. Run the installer on the machines where your manager and workers are installed. The installer detects installed components and automatically upgrades them. --- ## Pdftools OCR Service references Learn about parameters, languages, and custom profile configurations in the Pdftools OCR Service. --- ## Supported languages The Pdftools OCR Service only recognizes characters that are used in the languages you configured. For example, if you only choose English, some special characters like German umlauts (äöü) aren't recognized correctly and may appear as different letters (aou). Choose the languages used in the documents you OCR to avoid such mistakes. The Pdftools OCR Service supports the following languages: - [Natural languages](#natural-languages) - [Technical languages](#technical-languages) :::info[Additional language support] Before you use Arabic, Chinese, Hebrew, Japanese, Korean, or Thai in OCR analysis, contact us through the **[Contact page](https://www.pdf-tools.com/contact/)** for exact pricing information. OCR analysis of these languages has **additional costs**. ## Natural languages **Jump to:** | [A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) | [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | [X](#x) | [Y](#y) | [Z](#z) | ### A - **Abkhaz** – Abkhaz - **Adyghe** – Adyghe - **Afrikaans** – Afrikaans - **Agul** – Agul - **Albanian** – Albanian - **Altaic** – Altaic - **Arabic** – Arabic (Saudi Arabia)[^1] - **ArmenianEastern** – Armenian (Eastern) - **ArmenianGrabar** – Armenian (Grabar) - **ArmenianWestern** – Armenian (Western) - **Awar** – Avar - **Aymara** – Aymara - **AzeriCyrillic** – Azerbaijani (Cyrillic) - **AzeriLatin** – Azerbaijani (Latin) ### B - **Bashkir** – Bashkir - **Basque** – Basque - **Belarusian** – Belarussian - **Bemba** – Bemba - **Blackfoot** – Blackfoot - **Breton** – Breton - **Bugotu** – Bugotu - **Bulgarian** – Bulgarian - **Buryat** – Buryat ### C - **Catalan** – Catalan - **Chamorro** – Chamorro - **Chechen** – Chechen - **ChinesePRC** – Chinese Simplified[^1] - **ChineseTaiwan** – Chinese Traditional[^1] - **Chukcha** – Chukcha - **Chuvash** – Chuvash - **Corsican** – Corsican - **CrimeanTatar** – Crimean Tatar - **Croatian** – Croatian - **Crow** – Crow - **Czech** – Czech ### D - **Danish** – Danish - **Dargwa** – Dargwa - **Dungan** – Dungan - **Dutch** – Dutch (Netherlands) - **DutchBelgian** – Dutch (Belgium) ### E - **English** – English - **EskimoCyrillic** – Eskimo (Cyrillic) - **EskimoLatin** – Eskimo (Latin) - **Esperanto** – Esperanto - **Estonian** – Estonian - **Even** – Even - **Evenki** – Evenki ### F - **Faeroese** – Faeroese - **Fijian** – Fijian - **Finnish** – Finnish - **French** – French - **Frisian** – Frisian - **Friulian** – Friulian ### G - **GaelicScottish** – Scottish Gaelic - **Gagauz** – Gagauz - **Galician** – Galician - **Ganda** – Ganda - **German** – German - **GermanLuxembourg** – German (Luxembourg) - **GermanNewSpelling** – German (new spelling) - **Greek** – Greek - **Guarani** – Guarani ### H - **Hani** – Hani - **Hausa** – Hausa - **Hawaiian** – Hawaiian - **Hebrew** – Hebrew[^1] - **Hungarian** – Hungarian ### I - **Icelandic** – Icelandic - **Ido** – Ido - **Indonesian** – Indonesian - **Ingush** – Ingush - **Interlingua** – Interlingua - **Irish** – Irish - **Italian** – Italian ### J - **Japanese** – Japanese[^1] - **JapaneseModern** – Japanese (Modern)[^1] ### K - **Kabardian** – Kabardian - **Kalmyk** – Kalmyk - **KarachayBalkar** – Karachay-Balkar - **Karakalpak** – Karakalpak - **Kasub** – Kasub - **Kawa** – Kawa - **Kazakh** – Kazakh - **Khakas** – Khakas - **Khanty** – Khanty - **Kikuyu** – Kikuyu - **Kirgiz** – Kirghiz - **Kongo** – Kongo - **Korean** – Korean[^1] - **KoreanHangul** – Korean (Hangul)[^1] - **Koryak** – Koryak - **Kpelle** – Kpelle - **Kumyk** – Kumyk - **Kurdish** – Kurdish ### L - **Lak** – Lak - **Lappish** – Sami (Lappish) - **Latin** – Latin - **Latvian** – Latvian - **Lezgin** – Lezgin - **Lithuanian** – Lithuanian - **Luba** – Luba ### M - **Macedonian** – Macedonian - **Malagasy** – Malagasy - **Malay** – Malay - **Malinke** – Malinke - **Maltese** – Maltese - **Mansi** – Mansi - **Maori** – Maori - **Mari** – Mari - **Maya** – Maya - **Miao** – Miao - **Minankabaw** – Minangkabau - **Mohawk** – Mohawk - **Mongol** – Mongol - **Mordvin** – Mordvin ### N - **Nahuatl** – Nahuatl - **Nenets** – Nenets - **Nivkh** – Nivkh - **Nogay** – Nogay - **Norwegian** – Norwegian Nynorsk and Norwegian Bokmal - **NorwegianBokmal** – Norwegian (Bokmal) - **NorwegianNynorsk** – Norwegian (Nynorsk) - **Nyanja** – Nyanja ### O - **Occidental** – Occidental - **Ojibway** – Ojibway - **Ossetic** – Ossetian ### P - **Papiamento** – Papiamento - **PidginEnglish** – Tok Pisin - **Polish** – Polish - **PortugueseBrazilian** – Portuguese (Brazil) - **PortugueseStandard** – Portuguese (Portugal) - **Provencal** – Provencal ### Q - **Quechua** – Quechua ### R - **RhaetoRomanic** – Rhaeto-Romanic - **Romanian** – Romanian - **RomanianMoldavia** – Romanian (Moldavia) - **Romany** – Romany - **Ruanda** – Ruanda - **Rundi** – Rundi - **RussianOldSpelling** – Russian (old spelling) - **Russian** – Russian - **RussianWithAccent** – Russian with accents marking stress position ### S - **Samoan** – Samoan - **Selkup** – Selkup - **SerbianCyrillic** – Serbian (Cyrillic) - **SerbianLatin** – Serbian (Latin) - **Shona** – Shona - **Sioux** – Sioux (Dakota) - **Slovak** – Slovak - **Slovenian** – Slovenian - **Somali** – Somali - **Sorbian** – Sorbian - **Sotho** – Sotho - **Spanish** – Spanish - **Sunda** – Sunda - **Swahili** – Swahili - **Swazi** – Swazi - **Swedish** – Swedish ### T - **Tabassaran** – Tabassaran - **Tagalog** – Tagalog - **Tahitian** – Tahitian - **Tajik** – Tajik - **Tatar** – Tatar - **Thai** – Thai[^1] - **Tinpo** – Jingpo - **Tongan** – Tongan - **Tswana** – Tswana - **Tun** – Tun - **Turkish** – Turkish - **Turkmen** – Turkmen - **TurkmenLatin** – Turkmen (Latin) - **Tuvin** – Tuvan ### U - **Udmurt** – Udmurt - **UighurCyrillic** – Uighur (Cyrillic) - **UighurLatin** – Uighur (Latin) - **Ukrainian** – Ukrainian - **UzbekCyrillic** – Uzbek (Cyrillic) - **UzbekLatin** – Uzbek (Latin) ### V - **Visayan** – Cebuano ### W - **Welsh** – Welsh - **Wolof** – Wolof ### X - **Xhosa** – Xhosa ### Y - **Yakut** – Yakut ### Z - **Zapotec** – Zapotec - **Zulu** – Zulu ## Technical languages - **Basic** – Basic programming language - **C++** – C/C++ programming language - **Chemistry** – Simple chemical formulas - **Digits** – Numbers - **CMC7** – For MICR (CMC-7) text type - **Cobol** – Cobol programming language - **E13B** – For MICR (E-13B) text type - **Fortran** – Fortran programming language - **Java** – Java programming language - **OcrA** – For OCR-A text type - **OcrB** – For OCR-B text type - **Pascal** – Pascal programming language [^1]: Before you use Arabic, Chinese, Hebrew, Japanese, Korean, or Thai in OCR analysis, contact us through the **[Contact page](https://www.pdf-tools.com/contact/)** for exact pricing information. OCR analysis of these languages has **additional costs**. --- ## Parameters Pdftools OCR Service lets you fine-tune the OCR engine through parameters that influence performance, layout detection, output quality, and preprocessing steps. You can set these engine parameters as a sequence of key and value pairs separated by a semicolon (;) in the Conversion Service Configurator OCR settings. ## General settings ### `PredefinedProfile` | Key | Type | Default | |------------------|------|---------| | `PredefinedProfile` | Name | `Default` | Selects a predefined recognition profile. Each profile provides optimized OCR settings for a specific use case. | Profile name | Purpose | |-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`DataExtraction`](#dataextraction) | Captures all content from a document in a structured format, including tables, images, checkmarks, handwriting, and stamps. | | [`DocumentConversion_Accuracy`](#documentconversion_accuracy) | Converts documents into editable formats with the highest quality. Detects font styles and fully reconstructs the logical document structure. | | [`DocumentConversion_Normal`](#documentconversion_normal) | Converts documents into editable formats with faster processing. Detects font styles and reconstructs document structure, but skips orientation correction. | | [`DocumentArchiving_Accuracy`](#documentarchiving_accuracy) | Creates searchable PDF/PDF/A archives with maximum text coverage. Focuses on accuracy without reconstructing the full document structure. | | [`DocumentArchiving_Speed`](#documentarchiving_speed) | Creates searchable PDF/PDF/A archives with maximum throughput. Trades accuracy for faster processing. | | [`TextExtraction_Accuracy`](#textextraction_accuracy) | Extracts text from documents with high accuracy, including small and low-quality text areas. Doesn't detect images or tables. | | [`TextExtraction_Speed`](#textextraction_speed) | Extracts text from documents with maximum throughput. Trades accuracy for faster processing. | | [`FieldLevelRecognition`](#fieldlevelrecognition) | Recognizes short, isolated text fragments such as form fields or single lines. | | [`BarcodeRecognition_Accuracy`](#barcoderecognition_accuracy) | Detects and reads barcodes with high accuracy. All other content types (text, images, tables) are ignored. | | [`BarcodeRecognition_Speed`](#barcoderecognition_speed) | Detects and reads barcodes with maximum throughput. All other content types (text, images, tables) are ignored. | | [`HighCompressedImageOnlyPdf`](#highcompressedimageonlypdf) | Produces highly compressed PDF files where each page is stored as an image. No text recognition is performed. | | [`BusinessCardsProcessing`](#businesscardsprocessing) | Recognizes and extracts structured data from business cards. | | [`MachineReadableZone`](#machinereadablezone) | Reads machine-readable zone (MRZ) data from identity documents. Extracts all text on the image and performs automatic resolution and geometry correction. | | [`EngineeringDrawingsProcessing`](#engineeringdrawingsprocessing) | Recognizes text in technical drawings, engineering diagrams, and schematics. Handles large images and multiple text orientations, producing searchable PDF output. | | [`Default`](#default) | General-purpose profile that uses default values for all processing parameters. | --- #### `DataExtraction` Captures all content from a document in a structured format: - Identifies all object types: tables, images, checkmarks, handwriting, and stamps. - Uses accurate recognition mode for maximum quality. This profile corresponds to the following parameters:[^1] ```ini [PageAnalysisParams] AnalysisMode = PAM_TextExtraction SpeedQualityMode = SQM_Accurate DetectBarcodes = true DetectPictures = true DetectTables = true DetectHandwritten = true DetectCheckmarks = true DetectStamps = true DetectTextOnPictures = true DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Accurate TextTypes = TT_Normal | TT_Handwritten [SynthesisParamsForDocument] DetectDocumentStructure = true ``` --- #### `DocumentConversion_Accuracy` Converts documents into editable formats, optimized for accuracy: - Detects font styles (bold, italic, font size) and fully reconstructs the logical document structure (headings, lists, table of contents). This profile corresponds to the following parameters: ```ini [PageAnalysisParams] AnalysisMode = PAM_DocumentConversion SpeedQualityMode = SQM_Accurate DetectBarcodes = true DetectPictures = true DetectTables = true DetectHandwritten = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Accurate TextTypes = TT_Normal [SynthesisParamsForDocument] DetectDocumentStructure = true DetectFontFormatting = true ``` --- #### `DocumentConversion_Normal` Converts documents into editable formats, optimized for processing speed: - Detects font styles and reconstructs the logical document structure. - Skips image orientation correction to save time. - Uses fast analysis and normal recognition mode. This profile corresponds to the following parameters: ```ini [PagePreprocessingParams] CorrectOrientationMode = COM_No CorrectSkewMode = CSM_Fast [PageAnalysisParams] AnalysisMode = PAM_DocumentConversion SpeedQualityMode = SQM_Fast DetectBarcodes = false DetectPictures = true DetectTables = true DetectHandwritten = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Normal TextTypes = TT_Normal [SynthesisParamsForDocument] DetectDocumentStructure = true DetectFontFormatting = true ``` --- #### `DocumentArchiving_Accuracy` Creates searchable PDF/PDF/A archives, optimized for accuracy: - Maximizes text coverage, including text embedded in images. - Doesn't reconstruct the logical document structure or detect font styles. This profile corresponds to the following parameters: ```ini [PageAnalysisParams] AnalysisMode = PAM_TextExtraction SpeedQualityMode = SQM_Accurate DetectBarcodes = true DetectPictures = true DetectTables = false DetectHandwritten = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Accurate [SynthesisParamsForDocument] DetectDocumentStructure = false DetectFontFormatting = false [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = true DetectTextColor = TSPV_No DetectBackgroundColor = TSPV_No ``` --- #### `DocumentArchiving_Speed` Creates searchable PDF/PDF/A archives, optimized for speed: - Same goals as [`DocumentArchiving_Accuracy`](#documentarchiving_accuracy), but uses fast binarization, skips orientation correction and skew correction, and disables image, table, and barcode detection. This profile corresponds to the following parameters: ```ini [ObjectsExtractionParams] FastObjectsExtraction = true ProhibitColorImage = true [PagePreprocessingParams] UseFastBinarization = true CorrectOrientationMode = COM_No CorrectSkewMode = CSM_Fast CropImage = TSPV_No DetectImageType = TSPV_No StraightenLinesMode = SLM_Fast [PageAnalysisParams] AnalysisMode = PAM_TextExtraction SpeedQualityMode = SQM_Fast DetectBarcodes = false DetectPictures = false DetectTables = false DetectHandwritten = false DetectVerticalEuropeanText = false [RecognizerParams] Mode = RM_Fast [SynthesisParamsForDocument] DetectDocumentStructure = false DetectFontFormatting = false [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = true DetectTextColor = TSPV_No DetectBackgroundColor = TSPV_No ``` --- #### `TextExtraction_Accuracy` Extracts text from documents, optimized for accuracy: - Finds all text on the page, including small and low-quality text areas. Images and tables aren't detected. - Doesn't reconstruct the full logical document structure. This profile corresponds to the following parameters: ```ini [PageAnalysisParams] AnalysisMode = PAM_TextExtraction SpeedQualityMode = SQM_Accurate DetectBarcodes = true DetectPictures = false DetectTables = false DetectVectorGraphics = false DetectHandwritten = false DetectSeparators = true DetectCheckmarks = false DetectStamps = false DetectTextOnPictures = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Accurate [SynthesisParamsForDocument] DetectDocumentStructure = true DetectFontFormatting = false [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = true DetectTextColor = TSPV_No DetectBackgroundColor = TSPV_No ``` --- #### `TextExtraction_Speed` Extracts text from documents, optimized for speed: - Same goals as [`TextExtraction_Accuracy`](#textextraction_accuracy), but uses fast binarization, skips orientation correction, and discards color image data. This profile corresponds to the following parameters: ```ini [ObjectsExtractionParams] FastObjectsExtraction = true ProhibitColorImage = false [PagePreprocessingParams] UseFastBinarization = true DiscardColorImage = true CorrectOrientationMode = COM_No [PageAnalysisParams] AnalysisMode = PAM_TextExtraction SpeedQualityMode = SQM_Fast DetectBarcodes = false DetectPictures = false DetectTables = false DetectVectorGraphics = false DetectHandwritten = false DetectSeparators = true DetectCheckmarks = false DetectStamps = false DetectTextOnPictures = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Fast [SynthesisParamsForDocument] DetectDocumentStructure = false DetectFontFormatting = false [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = true DetectTextColor = TSPV_No DetectBackgroundColor = TSPV_No ``` --- #### `FieldLevelRecognition` Recognizes short, isolated text fragments such as form fields or single lines. This profile corresponds to the following parameters: ```ini [DocumentProcessingParams] PerformSynthesis = false [PageProcessingParams] PerformAnalysis = false [RecognizerParams] Mode = RM_Accurate [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = false ``` --- #### `BarcodeRecognition_Accuracy` Detects and reads barcodes, optimized for accuracy: - Only processes barcodes—text, images, and tables are ignored. This profile corresponds to the following parameters: ```ini [ObjectsExtractionParams] DetectMatrixPrinter = false DetectPorousText = false [PageAnalysisParams] DetectBarcodes = true DetectPictures = false DetectTables = false DetectText = false DetectSeparators = false DetectVectorGraphics = false [PagePreprocessingParams] CorrectSkewMode = CSM_Off ``` --- #### `BarcodeRecognition_Speed` Detects and reads barcodes, optimized for speed: - Same goals as [`BarcodeRecognition_Accuracy`](#barcoderecognition_accuracy), but uses fast object extraction, discards color image data, and skips preprocessing. This profile corresponds to the following parameters: ```ini [ObjectsExtractionParams] DetectMatrixPrinter = false DetectPorousText = false FastObjectsExtraction = true [PageAnalysisParams] DetectBarcodes = true DetectPictures = false DetectTables = false DetectText = false DetectSeparators = false DetectVectorGraphics = false [PagePreprocessingParams] CorrectSkewMode = CSM_Off DiscardColorImage = true StraightenLinesMode = SLM_Fast [PageProcessingParams] PerformPreprocessing = false ``` --- #### `HighCompressedImageOnlyPdf` Produces highly compressed image-only PDF files: - No text recognition or document structure analysis is performed. - Skew correction is turned off. - PDF export targets the smallest possible file size. - Each page is stored as a compressed image. This profile corresponds to the following parameters: ```ini [DocumentProcessingParams] PerformSynthesis = false [ObjectsExtractionParams] ProhibitColorImage = true [PageAnalysisParams] CollectPdfExportData = true AnalysisMode = PAM_TextOnly [PageProcessingParams] PerformRecognition = false [PDFExportParams] Scenario = PES_MinSize TextExportMode = PEM_ImageOnly [PagePreprocessingParams] CorrectSkewMode = CSM_Off ``` --- #### `BusinessCardsProcessing` Recognizes and extracts structured data from business cards: - Focuses on business card content—images and tables aren't detected. - Uses aggressive text extraction to capture small and low-quality text. - Applies resolution correction automatically. - Doesn't reconstruct the logical document structure. This profile corresponds to the following parameters: ```ini [ObjectsExtractionParams] EnableAggressiveTextExtraction = true ProhibitColorImage = false [PageAnalysisParams] PageObjectsUsageMode = POUM_BCR [PrepareImageMode] DocumentType = DT_BusinessCard [SynthesisParamsForDocument] DetectDocumentStructure = false [SynthesisParamsForPage] SynthesizeBusinessCards = true ``` --- #### `MachineReadableZone` Reads machine-readable zone (MRZ) data from identity documents: - Extracts all text on the page while ignoring images, vector graphics, and tables. - Automatically corrects resolution and geometry to handle varied scan quality. This profile corresponds to the following parameters: ```ini [PagePreprocessingParams] CorrectGeometry = TSPV_Auto CorrectOrientationMode = COM_Auto CorrectSkewMode = CSM_Auto OverwriteResolutionMode = ORM_Auto [PageAnalysisParams] AnalysisMode = PAM_TextOnly DetectPictures = false DetectSeparators = false DetectTables = false DetectText = true DetectVectorGraphics = false DetectTextOnPictures = true [ObjectsExtractionParams] EnableAggressiveTextExtraction = true RemoveGarbage = true RemoveTexture = true [RecognizerParams] Mode = RM_Accurate [SynthesisParamsForDocument] DetectFontFormatting = true [DocumentProcessingParams] PerformSynthesis = true ``` --- #### `EngineeringDrawingsProcessing` Recognizes text in technical drawings, engineering diagrams, and schematics: - Designed for large, complex images where text can appear at any orientation. - Finds all text on the page, including vertically oriented text blocks. This profile corresponds to the following parameters: ```ini [PageAnalysisParams] AnalysisMode = PAM_TextOnly DetectPictures = false DetectVectorGraphics = false DetectVerticalEuropeanText = true [RecognizerParams] Mode = RM_Accurate [FontFormattingDetectionParams] DetectFontFamily = true DetectBold = true DetectFontSize = true [SynthesisParamsForDocument] DetectDocumentStructure = false DetectFontFormatting = false [SynthesisParamsForPage] DetectFontFormattingAtPageLevel = true ``` --- #### `Default` General-purpose profile: - Uses default values for all processing parameters. --- ### `Profile` | Key | Type | |----------|------| | `Profile` | Path | Path to a custom recognition profile INI file. To configure a custom profile for specific OCR processing behavior, follow these steps: 1. Create a custom profile INI file. 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. 1. Navigate to the **OCR Settings** section. 1. Next to **Engine**, click the pen icon in the **Pdftools OCR Service (3H Legacy Compatible)** section. 1. In the **Parameters** input field, include a path to your INI file, for example: ```bash Profile="C:\ocr\profiles\document_conversion_high_accuracy.ini" ``` 1. After editing your configuration, click **Apply**. The INI file must be on the **same** machine as the **Pdftools OCR Service Manager** node. If both `Profile` and `PredefinedProfile` are set, the custom `Profile` **overrides** the predefined profile. :::info[Custom Profiles] For more details about creating your profiles, review **[Custom Profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/)** page. --- ### `PreprocessingOnly` | Key | Type | Default | |------------------|------|---------| | `PreprocessingOnly` | Boolean | `false` | When set to `true`, only image transformations (such as deskewing, resolution correction, and binarization) are applied—no recognition is performed. This is useful for workflows that require cleaned-up images without OCR. --- ### `RemoveGarbage` | Key | Type | |------------------|------| | `RemoveGarbage` | Integer | Remove small, isolated dark regions in bitonal images that are likely scanning noise before any OCR is done. The value defines the maximum area of such noise in pixels. A value of `-1` enables automatic determination. --- ## Blank page detection ### `RecognizeBlankPages` | Key | Type | Default | |------------------|------|---------| | `RecognizeBlankPages` | Boolean | `false` | Enable automatic skipping of pages that are considered blank. A blank page is a page with uniform coloring and only slight noise. Colored, grayscale, and bitonal pages can be subject to blank page recognition. If a page is skipped as blank, no OCR is performed. The `RecognizeBlankPages` parameter takes Boolean values `true` or `false`. --- ### `BlankPageMargin` | Key | Type | Default | |------------------|------|---------| | `BlankPageMargin` | Double | `0.02` | Set the ratio that the margin takes with respect to the corresponding page length. The margin is excluded from the analysis when a page is blank, preventing border artifacts from affecting blank page detection. Allowed values range from `0.0` to `0.5`. This parameter is only active if the value of [RecognizeBlankPages](#recognizeblankpages) is set to `true`. --- ## Output format control ### `DisableMaskEmbedding` | Key | Type | Default | |------------------|------|---------| | `DisableMaskEmbedding` | Boolean | `false` | If this option is set to `true`, no mask is embedded in the output TIFF. When set to `false` (default), bitonal masks are embedded in the output TIFF or PDF as an image layer. The mask layer is omitted when enabled, and only recognized text is preserved. The `DisableMaskEmbedding` is useful for output without background images. The `DisableMaskEmbedding` parameter takes Boolean values `true` or `false`. [^1]: All occurrences of sentence "*profile corresponds to the following parameters*" reference a custom profile INI file with an equivalent configuration to a predefined profile. For more information, review [`Profile`](#profile), and [Custom Profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/). --- ## Custom profiles A custom profile is an INI-format configuration file that lets you adjust parameters for image preprocessing, page analysis, text recognition, and document synthesis. Custom profile settings take precedence over predefined profile settings. The following code is an example of a custom profile INI configuration file: ```ini [PagePreprocessingParams] DiscardColorImage = false [RecognizerParams] Mode = RM_Accurate TextLanguage = English,German ``` To configure a custom profile for specific OCR processing behavior, follow these steps: 1. Create a custom profile INI file. 1. In the Conversion Service Configurator, go to **Workflows & Profiles**. 1. Click the pen icon next to the workflow profile you want to edit. 1. Navigate to the **OCR Settings** section. 1. Next to **Engine**, click the pen icon in the **Pdftools OCR Service (3H Legacy Compatible)** section. 1. In the **Parameters** input field, include a path to your INI file, for example: ```bash Profile="C:\ocr\profiles\document_conversion_high_accuracy.ini" ``` 1. After editing your configuration, click **Apply**. The INI file must be on the **same** machine as the **Pdftools OCR Service Manager** node. If both `Profile` and `PredefinedProfile` are set, the custom `Profile` **overrides** the predefined profile. ## Profile file format Custom profiles use the **INI format**. Each section is identified by a name in square brackets and contains key-value pairs that configure a specific aspect of OCR processing. You can add comments by starting a line with a semicolon (`;`). Property values use the following formats: - **Boolean**: `true` or `false` - **Enum**: The constant name (for example, `RM_Accurate`) - **String**: The value without quotes ### Profile file structure A profile consists of multiple sections, such as: - `[PrepareImageMode]` - `[PagePreprocessingParams]` - `[DocumentProcessingParams]` - `[RecognizerParams]` - `[SynthesisParamsForPage]` Each section contains key-value pairs that configure a particular aspect of OCR processing. For the full list of available sections, refer to [Key INI file sections and their purpose](#key-ini-file-sections-and-their-purpose). ### How profiles are used - To use a custom profile, pass the path to the `Profile` parameter. - If you set both `Profile` and `PredefinedProfile`, the custom profile's values take precedence for any overlapping parameters. - Pdftools OCR Service validates the profile when processing begins. :::warning[File path] The profile file must exist on a path reachable by Pdftools OCR Service Manager. If Pdftools OCR Service can't find the file or the file contains syntax errors, it returns an error. ## Tips for writing effective profiles - Always verify your INI file encoding (UTF-8 without BOM). - Build incrementally: start with minimal settings, then add new sections one at a time. - Don't turn on modules you don't need. For example, `DetectBarcodes` unless required. - Use language combinations carefully. More languages increase processing time. - Prefer 300 DPI images for optimal OCR accuracy. ## Key INI file sections and their purpose The following table includes links to the references of specific INI file sections: | INI file section | Description | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| | [`[PrepareImageMode]`](./prepareimagemode.mdx) | Configure image preparation: compression, document type, image source type, and annotations. | | [`[ImageProcessingParams]`](./imageprocessingparams.mdx) | Adjust rotation, mirroring, and color inversion for image blocks. | | [`[DocumentProcessingParams]`](./documentprocessingparams.mdx) | Control whether document synthesis runs. | | [`[PageProcessingParams]`](./pageprocessingparams.mdx) | Configure preprocessing, layout analysis, and recognition. | | [`[PagePreprocessingParams]`](./pagepreprocessingparams.mdx) | Set options for correcting orientation, skew, geometry, resolution, binarization, and cropping. | | [`[PageAnalysisParams]`](./pageanalysisparams.mdx) | Control layout analysis: detect tables, images, barcodes, and structures. | | [`[TableAnalysisParams]`](./tableanalysisparams.mdx) | Configure table structure analysis and interpretation. | | [`[TextLayerInjectionParams]`](./textlayerinjectionparams.mdx) | Tune parameters for creating a searchable PDF with text layer injection. | | [`[BarcodeParams]`](./barcodeparams.mdx) | Detect, decode, and configure interpretation of barcode types. | | [`[ObjectsExtractionParams]`](./objectsextractionparams.mdx) | Manage object extraction, noise cleanup, and embedded text detection. | | [`[RecognizerParams]`](./recognizerparams.mdx) | Define OCR language, text types, recognition speed, and fine-tuning. | | [`[SortingBlocksParams]`](./sortingblocksparams.mdx) | Set parameters for combining blocks of data into groups. | | [`[SynthesisParamsForPage]`](./synthesisparamsforpage.mdx) | Configure page-level layout synthesis and formatting detection. | | [`[SynthesisParamsForDocument]`](./synthesisparamsfordocument.mdx) | Manage document-level synthesis, structure, formatting, and memory usage. | | [`[DocumentStructureDetectionParams]`](./documentstructuredetectionparams.mdx) | Configure document structure detection: headlines, footnotes, table of contents, and columns. | | [`[FontFormattingDetectionParams]`](./fontformattingdetectionparams.mdx) | Detect bold, italic, font size, spacing, and other typographic features. | --- ## [BarcodeParams] INI file section The `[BarcodeParams]` INI file section defines parameters for barcode detection and recognition. These parameters are only used when the [`DetectBarcodes`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/pageanalysisparams#detectbarcodes) property in the `[PageAnalysisParams]` section is set to `true`. --- ## Main settings ### `EnableBarcodesCheck` | Key | Type | Default | |----------------------|---------|---------| | `EnableBarcodesCheck` | Boolean | `true` | Specifies whether the barcode checking classifier can be used. This classifier verifies if there are barcodes on the image. This property doesn't work with postal barcodes. --- ### `Type` | Key | Type | Default | |--------|---------------------------------------|-----------------| | `Type` | [`BarcodeTypeEnum`](#barcodetypeenum) | `BT_Autodetect` | The value of this property is an OR superposition of the [`BarcodeTypeEnum`](#barcodetypeenum) enumeration constants that denote the types of barcodes. For example, if it is set to `BT_EAN13 | BT_EAN8`, the Pdftools OCR Service tries to recognize barcode blocks in either EAN 13 or EAN 8 standard, ignoring all other variants. By default, this property is set to `BT_Autodetect`, the Pdftools OCR Service detects the barcode type automatically. **note: The default value allows detection of all supported barcode types. However, consider removing IATA 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 barcode types unless you're certain they occur on your images. Barcodes of these types don't have a checksum and can be mistakenly found on image areas that don't actually contain barcodes.** #### `BarcodeTypeEnum` - `BT_Autodetect`: Forces the Pdftools OCR Service to automatically detect the barcode type during recognition. - `BT_AutodetectWithoutPostal`: Automatically detects the barcode type during recognition, except postal types. - `BT_Australia4State`: Barcode in Australia 4-State standard. - `BT_Aztec`: Barcode in Aztec standard. - `BT_Codabar`: Barcode in Codabar standard. - `BT_Code128`: Barcode in Code 128 standard. - `BT_Code32`: Barcode in Code 32 standard. - `BT_Code39`: Barcode in Code 39 standard. - `BT_Code93`: Barcode in Code 93 standard. - `BT_DataMatrix`: Barcode in Data Matrix standard. - `BT_EAN13`: Barcode in EAN 13 standard. - `BT_EAN8`: Barcode in EAN 8 standard. - `BT_FullAscii`: Barcode in Full ASCII Code 39 standard. - `BT_IATA25`: Barcode in IATA 2 of 5 standard. - `BT_Industrial25`: Barcode in Industrial 2 of 5 standard. - `BT_IntelligentMail`: Barcode in Intelligent Mail standard. - `BT_Interleaved25`: Barcode in Interleaved 2 of 5 standard. - `BT_JapanPost`: Barcode in Japan Post standard. - `BT_KIX`: Barcode in KIX standard. - `BT_Matrix25`: Barcode in Matrix 2 of 5 standard. - `BT_MaxiCode`: Barcode in MaxiCode standard. - `BT_Patch`: Barcode in Patch standard. - `BT_PDF417`: Barcode in PDF417 standard. - `BT_PostNet`: Barcode in PostNet standard. - `BT_QRCode`: Barcode in QR Code standard. - `BT_RoyalMail4State`: Barcode in Royal Mail 4-State standard. - `BT_UCC128`: Barcode in GS1-128 standard. Formerly called UCC-128. - `BT_Unknown`: Denotes an unknown type of barcode. - `BT_UPCA`: Barcode in UPC-A standard. - `BT_UPCE`: Barcode in UPC-E standard. --- ### `Orientation` | Key | Type | Default | |---------------|-----------------------------------------------------|-----------------| | `Orientation` | [`BarcodeOrientationEnum`](#barcodeorientationenum) | `BO_Autodetect` | The value of this property is an OR superposition of the [`BarcodeOrientationEnum`](#barcodeorientationenum) constants which define barcode orientations. For example, if set to `BO_Left_To_Right | BO_Down_To_Top`, the Pdftools OCR Service assumes barcode blocks may be oriented either from left to right or from down to top, ignoring all others. #### `BarcodeOrientationEnum` - `BO_Autodetect`: Detect the barcode orientation automatically. - `BO_Down_To_Top`: Barcode is oriented from down to top. - `BO_Left_To_Right`: Barcode is oriented from left to right. - `BO_Right_To_Left`: Barcode is oriented from right to left. - `BO_Top_To_Down`: Barcode is oriented from top to down. - `BO_Unknown`: Denotes an unknown type of barcode orientation. --- ## Settings for specific barcode types ### `CodePage` | Key | Type | Default | |------------|---------------------------------|-----------| | `CodePage` | [`CodePageEnum`](#codepageenum) | `CP_Null` | This property is used to recognize PDF417, Aztec, Data Matrix, QR Code, and MaxiCode barcodes that **do not conform to the barcode specifications**. Do **not** use this property for barcodes that **do** conform to the specifications. Some barcode printers use code pages that are different from those defined in the barcode standard. In such cases, use this property to specify the code page that was used by the barcode printer to create the barcode. In most cases, this is the code page of the operating system the printer was running on. **note: The following code pages are required by the specifications:** - For **PDF417**: DOS United States (437): `CP_US_MSDOS` - For **Aztec, DataMatrix, QR Code, MaxiCode**: ISO Latin 1 (8859-1): `CP_Latin_ISO` This property is used to convert recognized barcode data into a Unicode string. By default, this property is set to `CP_Null`, which means that the code page required by the specification should be used. #### `CodePageEnum` - `CP_Armenian`: Windows Armenian - `CP_Armenian_Macintosh`: Macintosh Armenian - `CP_Armenian_MSDOS`: DOS Armenian - `CP_Baltic`: Windows Baltic (1257) - `CP_Baltic_ISO`: ISO Baltic (8859-4) - `CP_Baltic_MSDOS`: DOS Baltic (775) - `CP_Bashkir`: Windows Bashkir - `CP_Chinese_Simpl_GB`: Chinese Simplified (GB2312) - `CP_Chinese_Simpl_Mac`: Chinese Simplified (Mac) - `CP_Chinese_Trad_Big`: Chinese Traditional (Big5) - `CP_Chinese_Trad_Mac`: Chinese Traditional (Mac) - `CP_Croatian_Macintosh`: Macintosh Croatian - `CP_Cyrillic`: Windows Cyrillic (1251) - `CP_Cyrillic_ISO`: ISO Cyrillic (8859-5) - `CP_Cyrillic_Macintosh`: Macintosh Cyrillic - `CP_Cyrillic_MSDOS`: DOS Cyrillic (855) - `CP_Digits`: Digits - `CP_EasternEuropean`: Windows Central Europe (1250) - `CP_EasternEuropean_ISO`: ISO Central Europe (8859-2) - `CP_Greek`: Windows Greek (1253) - `CP_Greek_737`: DOS Greek (737) - `CP_Greek_869`: DOS Modern Greek (869) - `CP_Greek_ISO`: ISO Greek (8859-7) - `CP_Greek_Macintosh`: Macintosh Greek 1 - `CP_Hebrew`: Windows Hebrew (1255) - `CP_Hebrew_ISO`: ISO Hebrew (8859-8) - `CP_Hebrew_Macintosh`: Macintosh Hebrew - `CP_Hebrew_MSDOS`: DOS Hebrew (862) - `CP_Icelandic_Macintosh`: Macintosh Icelandic - `CP_Japan_Mac`: Japanese (Mac) - `CP_Japan_SJIS`: Japanese (Shift-JIS) - `CP_KOI8`: Russian KOI8 - `CP_Korean`: Korean - `CP_Korean_Johab`: Korean (Johab) - `CP_Korean_Mac`: Korean (Mac) - `CP_Latin`: Windows Western Europe (1252) - `CP_Latin_ISO`: ISO Latin 1 (8859-1) - `CP_Latin2_Macintosh`: Macintosh Latin 2 - `CP_Latin5_ISO`: ISO Turkish (8859-9) - `CP_Latin1_MSDOS`: DOS Multilingual Latin 1 - `CP_Mathematical`: Mathematical symbols - `CP_Null`: Invalid code page - `CP_Roman_Macintosh`: Macintosh Roman - `CP_Russian_MSDOS`: DOS Russian (866) - `CP_Slavic_MSDOS`: DOS Latin 2 (852) - `CP_Tatar`: Windows Tatar - `CP_Tatar_MSDOS`: DOS Tatar - `CP_Thai`: Windows Thai (874) - `CP_Thai_Macintosh`: Macintosh Thai - `CP_Turkish`: Windows Turkish (1254) - `CP_Turkish_IBM`: DOS Turkish (857) - `CP_Turkish_ISO`: ISO Latin 3 (8859-3) - `CP_Turkish_Macintosh`: Macintosh Turkish - `CP_Ukrainian_Macintosh`: Macintosh Ukrainian - `CP_US_MSDOS`: DOS United States (437) --- ### `ContainsBinaryData` | Key | Type | Default | |----------------------|---------|---------| | `ContainsBinaryData` | Boolean | `false` | This property is relevant only for barcodes like PDF417, Aztec, Data Matrix, and QR Code that encode some binary data. It affects how binary data is represented in the recognized output. If set to `true`, the binary data in the barcode is saved as a sequence of hexadecimal values for corresponding bytes. If set to `false`, the binary data is translated to a Unicode string using the code page specified in the `CodePage` property. --- ### `HasChecksum` | Key | Type | Default | |--------------|---------|---------| | `HasChecksum` | Boolean | `false` | Specifies whether the barcode must be interpreted with a checksum. Only applicable for **Code 39**, **Interleaved 2 of 5**, **Codabar**, and **Matrix 2 of 5**. **note: While Codabar has no check digit, Pdftools OCR Service uses a Modulo 16 algorithm to compute one.** Each Codabar character has a value. The sum of all values (including Start/Stop characters) is computed, and the check digit is a value that brings this total to a multiple of 16. --- ### `SupplementType` | Key | Type | Default | |------------------|-----------------------------------------------------------|-----------------| | `SupplementType` | [`BarcodeSupplementTypeEnum`](#barcodesupplementtypeenum) | `BS_Autodetect` | This property defines the type of supplementary barcode for EAN-8, EAN-13, UPC-A, and UPC-E barcodes. It is an OR combination of [`BarcodeSupplementTypeEnum`](#barcodesupplementtypeenum) values. For example, setting it to `BS_Void` or `BS_2Digits` lets the Pdftools OCR Service try to recognize barcodes either with no supplement or with a 2-digit supplement. #### `BarcodeSupplementTypeEnum` - `BS_2Digits`: 2-digit supplementary barcode. - `BS_5Digits`: 5-digit supplementary barcode. - `BS_Autodetect`: Automatically detect the supplementary barcode type. - `BS_Void`: No supplementary barcode. --- ## [DocumentProcessingParams] INI file section The `[DocumentProcessingParams]` section controls document-level processing, including whether document synthesis runs after page recognition. This section groups together: - **Page processing** — configured in the [`[PageProcessingParams]`](./pageprocessingparams.mdx) section, which controls preprocessing, layout analysis, and recognition for each page. - **Document synthesis** — configured in the [`[SynthesisParamsForDocument]`](./synthesisparamsfordocument.mdx) section, which controls structure detection, font formatting, and memory optimization. --- ### `PerformSynthesis` | Key | Type | Default | |--------------------|-----------|---------| | `PerformSynthesis` | `Boolean` | `true` | Specifies whether Pdftools OCR Service performs document synthesis after page recognition. If this property is `false`, the [`[SynthesisParamsForDocument]`](./synthesisparamsfordocument.mdx) section is ignored. --- ## [DocumentStructureDetectionParams] INI file section The `[DocumentStructureDetectionParams]` INI file section defines parameters for detecting document structural elements such as headlines, footnotes, table of contents, and columns during document synthesis. You can turn off any of these properties if your document doesn't contain the corresponding elements, which may speed up processing. **info: These parameters are only used when the [`DetectDocumentStructure`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/synthesisparamsfordocument#detectdocumentstructure) property in the `[SynthesisParamsForDocument]` section is set to `true`.** --- ### `DetectHeadlines` | Key | Type | Default | |-------------------|-----------|---------| | `DetectHeadlines` | `Boolean` | `true` | If this property is set to `true`, headlines are detected during document synthesis. --- ### `DetectFootnotes` | Key | Type | Default | |-------------------|-----------|---------| | `DetectFootnotes` | `Boolean` | `true` | If this property is set to `true`, footnotes are detected during document synthesis. --- ### `DetectCaptions` | Key | Type | Default | |------------------|-----------|---------| | `DetectCaptions` | `Boolean` | `true` | If this property is set to `true`, captions are detected during document synthesis. --- ### `DetectColumns` | Key | Type | Default | |-----------------|-----------|---------| | `DetectColumns` | `Boolean` | `true` | If this property is set to `true`, columns are detected during document synthesis. --- ### `DetectLists` | Key | Type | Default | |---------------|-----------|---------| | `DetectLists` | `Boolean` | `true` | If this property is set to `true`, lists are detected during document synthesis. --- ### `DetectRunningTitles` | Key | Type | Default | |-----------------------|-----------|---------| | `DetectRunningTitles` | `Boolean` | `true` | If this property is set to `true`, running titles (headers and footers) are detected during document synthesis. --- ### `DetectTableOfContents` | Key | Type | Default | |-------------------------|-----------|---------| | `DetectTableOfContents` | `Boolean` | `true` | If this property is set to `true`, the table of contents is detected during document synthesis. --- ### `DetectOverflowingParagraphs` | Key | Type | Default | |-------------------------------|-----------|---------| | `DetectOverflowingParagraphs` | `Boolean` | `true` | If this property is set to `true`, overflowing paragraphs are detected during document synthesis. An overflowing paragraph is one that starts on one page and ends on another. If the property is set to `false`, Pdftools OCR Service presumes that there are no overflowing paragraphs in the document. --- ### `ClassifySeparators` | Key | Type | Default | |-----------------------|-----------|---------| | `ClassifySeparators` | `Boolean` | `true` | If this property is set to `true`, additional properties of separators (such as their type and role) are detected during document synthesis. --- ## [FontFormattingDetectionParams] INI file section The `[FontFormattingDetectionParams]` INI file section defines parameters for detecting font formatting and typographic attributes such as bold, italics, font family, size, and spacing during OCR text synthesis. --- ## Text decoration ### `DetectBold` | Key | Type | Default | |--------------|-----------|---------| | `DetectBold` | `Boolean` | `true` | When set to `true`, bold formatting is identified during synthesis. --- ### `DetectItalic` | Key | Type | Default | |----------------|-----------|---------| | `DetectItalic` | `Boolean` | `true` | When set to `true`, italic formatting is identified during synthesis. --- ### `DetectSubscriptsSuperscripts` | Key | Type | Default | |--------------------------------|-----------|---------| | `DetectSubscriptsSuperscripts` | `Boolean` | `true` | When set to `true`, subscript and superscript text is identified during synthesis. --- ### `DetectUnderlineStrikeout` | Key | Type | Default | |----------------------------|-----------|---------| | `DetectUnderlineStrikeout` | `Boolean` | `true` | When set to `true`, underlined and struck-through text is identified during synthesis. --- ### `DetectSmallCaps` | Key | Type | Default | |-------------------|-----------|---------| | `DetectSmallCaps` | `Boolean` | `true` | When set to `true`, small capitals are identified during synthesis. --- ### `DetectDropCaps` | Key | Type | Default | |------------------|-----------|---------| | `DetectDropCaps` | `Boolean` | `true` | When set to `true`, enlarged initial letters (drop caps) are identified during synthesis. --- ## Font attributes ### `DetectFontFamily` | Key | Type | Default | |--------------------|-----------|---------| | `DetectFontFamily` | `Boolean` | `true` | When set to `true`, the font family is identified during synthesis. --- ### `DetectFontSize` | Key | Type | Default | |------------------|-----------|---------| | `DetectFontSize` | `Boolean` | `true` | When set to `true`, the font size is identified during synthesis. --- ### `DetectSerifs` | Key | Type | Default | |----------------|-----------|---------| | `DetectSerifs` | `Boolean` | `true` | When set to `true`, Pdftools OCR Service distinguishes between serif and sans-serif typefaces during synthesis and selects the matching font category for the output text. When set to `false`, this distinction is ignored and the best-fitting font is chosen regardless of whether the original text uses a serif or sans-serif typeface. --- ## Scaling and spacing ### `DetectScaling` | Key | Type | Default | |-----------------|-----------|---------| | `DetectScaling` | `Boolean` | `true` | When set to `true`, character scaling (horizontal stretch or compression) is identified during synthesis. --- ### `DetectSpacing` | Key | Type | Default | |-----------------|-----------|---------| | `DetectSpacing` | `Boolean` | `false` | When set to `true`, character spacing is identified during synthesis. --- ### `MonospaceDetectionMode` | Key | Type | Default | |--------------------------|-------------------------------------------------------------|------------| | `MonospaceDetectionMode` | [`MonospaceDetectionModeEnum`](#monospacedetectionmodeenum) | `MDM_Auto` | Controls how monospace fonts are handled during synthesis. #### `MonospaceDetectionModeEnum` - `MDM_Auto`: Automatically determines whether the text uses a monospace font. - `MDM_Ignore`: Skips monospace detection entirely. - `MDM_Monospace`: Treats all output text as monospace. - `MDM_NotMonospace`: Treats all output text as proportional (non-monospace). --- ## [ImageProcessingParams] INI file section These options control how the OCR engine transforms individual [image blocks](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/pageanalysisparams#block-detection) before recognition by adjusting their rotation, mirroring, or color inversion to ensure correct text orientation. When both rotation and mirroring are configured, rotation is applied first, followed by mirroring. --- ### `InvertImage` | Key | Type | Default | |---------------|-----------|---------| | `InvertImage` | `Boolean` | `false` | Specifies if the image colors in the block are inverted. If this property is `true`, Pdftools OCR Service inverts the image of a block before recognition. --- ### `MirrorImage` | Key | Type | Default | |---------------|-----------|---------| | `MirrorImage` | `Boolean` | `false` | Specifies if the image in the block is mirrored around the vertical axis. If this property is `true`, Pdftools OCR Service mirrors the image of a block before recognition. --- ### `RotationType` | Key | Type | Default | |----------------|---------------------------------------------------------------|-----------------| | `RotationType` | [`RotationTypeEnum`](#rotationtypeenum) | `RT_NoRotation` | Specifies the orientation of a text in a block relative to the normal reading position. Supported values are in [`RotationTypeEnum`](#rotationtypeenum). - This property **cannot be set** to `RT_UnknownRotation`. - The default value `RT_NoRotation` means that the orientation is normal. #### `RotationTypeEnum` The `RotationTypeEnum` defines the set of possible rotation modes that can be applied to an image during preprocessing, such as 90° clockwise or upside down. It is used to control the `RotationType` key in OCR configuration profiles. - `RT_Clockwise`: Rotate an image 90° clockwise. - `RT_Counterclockwise`: Rotate an image 90° counterclockwise. - `RT_NoRotation`: Do not rotate an image. - `RT_Upsidedown`: Rotate an image upside down. - `RT_UnknownRotation`: The rotation angle is undefined. --- ## [ObjectsExtractionParams] INI file section The `[ObjectsExtractionParams]` INI file section controls how Pdftools OCR Service extracts, filters, and detects visual objects and text elements from scanned images. --- ## Common settings ### `FastObjectsExtraction` | Key | Type | Default | |-------------------------|---------|---------| | `FastObjectsExtraction` | Boolean | `false` | If this property is set to `true`, object extraction speeds up, but quality may deteriorate. --- ### `ProhibitColorImage` | Key | Type | Default | |----------------------|---------|---------| | `ProhibitColorImage` | Boolean | `false` | If set to `true`, Pdftools OCR Service uses only a black-and-white plane during object extraction. Detection quality for colored tables and images may be reduced. --- ### `SourceContentReuseMode` | Key | Type | Default | |--------------------------|-----------------------------------------------------------------|------------| | `SourceContentReuseMode` | [`SourceContentReuseModeEnum`](#sourcecontentreusemodeenum) | `CRM_Auto` | Specifies how to use the text and image layers of the source PDF file. #### `SourceContentReuseModeEnum` - `CRM_Auto`: Automatically selects how to reuse source content from PDF files. If the result doesn't meet expectations, or you know the document type in advance, select the mode manually. - `CRM_ContentAndPictures`: Automatically selects whether to use the source text or rasterized image for each part of a page. If the text from the source file is considered reliable, it's used; otherwise, the text from the raster is used. - `CRM_ContentOnly`: Uses both the text and image layers of the source PDF file directly. :::caution Using the text contents of the source file speeds up processing, but if you choose this mode and there's no text layer, an error occurs. Use this mode for source files with visible text encoded in Unicode, ASCII, or another character encoding standard, with correct font and size settings. For other file types, use `CRM_Auto`, `CRM_ContentAndPictures`, or `CRM_DoNotReuse`. ::: - `CRM_DoNotReuse`: Rasterizes the pages of the source PDF file and processes them. The contents of the source file are ignored. --- ## Removing objects ### `RemoveGarbage` | Key | Type | Default | |-----------------|---------|---------| | `RemoveGarbage` | Boolean | `false` | Specifies whether to remove "garbage" (for example, dots smaller than a certain size) from the image during object extraction. --- ### `RemoveTexture` | Key | Type | Default | |-----------------|---------|---------| | `RemoveTexture` | Boolean | `true` | If set to `true`, Pdftools OCR Service removes background texture noise from a temporary image used for recognition. The source image itself remains unchanged. --- ## Detecting objects ### `DetectMatrixPrinter` | Key | Type | Default | |-----------------------|---------|---------| | `DetectMatrixPrinter` | Boolean | `true` | If this property is set to `true`, text printed using a matrix printer is detected during objects extraction. --- ### `DetectPorousText` | Key | Type | Default | |--------------------|---------|---------| | `DetectPorousText` | Boolean | `true` | If set to `true`, regions with porous text are detected during objects extraction. --- ### `EnableAggressiveTextExtraction` | Key | Type | Default | |----------------------------------|---------|---------| | `EnableAggressiveTextExtraction` | Boolean | `false` | If set to `true`, Pdftools OCR Service attempts to extract as much text as possible, even from low-quality images. Recommended when the input contains degraded or faint text. **warning: The `EnableAggressiveTextExtraction` mode may lead to misinterpreting pictures as text or vertically rearranging horizontal text.** --- ### `ProhibitDottedSeparators` | Key | Type | Default | |----------------------------|---------|---------| | `ProhibitDottedSeparators` | Boolean | `false` | If this property is set to `true`, Pdftools OCR Service presumes that the document does **not** contain dotted separators. This can be useful if you're certain the document lacks dotted separators or if some content is mistakenly identified as one. --- ## [PageAnalysisParams] INI file section The `[PageAnalysisParams]` INI file section defines parameters controlling how the Pdftools OCR Service analyzes page content during layout analysis, including detecting text, tables, images, barcodes, and layout structures. --- ## Analysis mode ### `AnalysisMode` | Key | Type | Default | |----------------|-----------------------------------------------------|--------------------------| | `AnalysisMode` | [`PageAnalysisModeEnum`](#pageanalysismodeenum) | `PAM_DocumentConversion` | Specifies the layout analysis mode. For documents with tables, complex layouts, or many different object types, set this property to `PAM_TextExtraction`. #### `PageAnalysisModeEnum` - `PAM_DocumentConversion`: Optimized for documents that primarily contain text. - `PAM_TextExtraction`: Optimized for documents with mixed layouts, tables, and other object types that the export needs to preserve (for example, invoices). --- ### `SpeedQualityMode` | Key | Type | Default | |--------------------|-------------------------------------------------------|------------| | `SpeedQualityMode` | [`SpeedQualityModeEnum`](#speedqualitymodeenum) | `SQM_Fast` | Manages the balance between analysis accuracy and speed. You may need the `SQM_Accurate` setting when processing documents with complex backgrounds or watermarks. #### `SpeedQualityModeEnum` - `SQM_Fast`: Prioritizes speed over accuracy. Suitable for documents without complex color patterns or watermarks. - `SQM_Accurate`: Prioritizes accuracy over speed. Use this mode for documents with complex or colorful backgrounds or watermarks. --- ## Block detection During layout analysis, Pdftools OCR Service segments each page into rectangular regions called *blocks*. Each block represents a distinct content area: a paragraph of text, a table, an image, or a barcode. The parameters in this section control which content types the engine detects and assigns to dedicated blocks. Content that doesn't match a specific type may still appear in the layout as a generic type such as a picture. After detection, Pdftools OCR Service sorts blocks into reading order based on their position on the page. You can fine-tune how blocks group together during this ordering step with the [`[SortingBlocksParams]`](./sortingblocksparams.mdx) section, and adjust how the engine processes each block's image (rotation, mirroring, inversion) with the [`[ImageProcessingParams]`](./imageprocessingparams.mdx) section. ### `DetectText` | Key | Type | Default | |--------------|---------|---------| | `DetectText` | Boolean | `true` | If this property is `true`, text areas are detected during layout analysis. --- ### `DetectHandwritten` | Key | Type | Default | |--------------------|---------|---------| | `DetectHandwritten` | Boolean | `false` | When set to `true`, enables detection of handwritten text. Handwritten text can only be detected if the [`SpeedQualityMode`](#speedqualitymode) property is set to `SQM_Accurate`; otherwise, this setting is ignored. --- ### `DetectTables` | Key | Type | Default | |----------------|---------|---------| | `DetectTables` | Boolean | `true` | If this property is `true`, tables are detected during layout analysis. Table detection parameters are configured in the [`[TableAnalysisParams]`](./tableanalysisparams.mdx) section. --- ### `DetectBarcodes` | Key | Type | Default | |------------------|---------|---------| | `DetectBarcodes` | Boolean | `false` | Specifies if barcodes are detected and barcode blocks are created during layout analysis. If this property is `false`, barcodes may be detected as blocks of some other type (for example, pictures). Barcode recognition parameters are configured in the [`[BarcodeParams]`](./barcodeparams.mdx) section. --- ### `DetectCheckmarks` | Key | Type | Default | |--------------------|---------|---------| | `DetectCheckmarks` | Boolean | `false` | If this property is `true`, checkmarks are detected during layout analysis. --- ### `DetectSeparators` | Key | Type | Default | |--------------------|---------|---------| | `DetectSeparators` | Boolean | `true` | If this property is `true`, separators are detected during layout analysis. --- ### `DetectPictures` | Key | Type | Default | |------------------|---------|---------| | `DetectPictures` | Boolean | `true` | If this property is `true`, pictures are detected during layout analysis. --- ### `DetectVectorGraphics` | Key | Type | Default | |------------------------|---------|---------| | `DetectVectorGraphics` | Boolean | `true` | If this property is `true`, vector pictures are detected during layout analysis. Vector picture blocks may appear in the layout only if this property was set to `true` during layout analysis. --- ### `DetectStamps` | Key | Type | Default | |----------------|---------|---------| | `DetectStamps` | Boolean | `false` | If this property is `true`, stamps are detected during layout analysis and placed into picture blocks. The text on detected stamps isn't recognized. Stamps can only be detected if the [`SpeedQualityMode`](#speedqualitymode) property is set to `SQM_Accurate`; otherwise, this setting is ignored. --- ## Additional settings ### `NoShadowsMode` | Key | Type | Default | |-----------------|---------|---------| | `NoShadowsMode` | Boolean | `false` | When set to `true`, the Pdftools OCR Service presumes that an image has no shadows from scanning. --- ### `PaperSizeDetectionMode` | Key | Type | Default | |--------------------------|-----------------------------------------------------------------|-------------| | `PaperSizeDetectionMode` | [`PaperSizeDetectionModeEnum`](#papersizedetectionmodeenum) | `PSDM_Auto` | Indicates if the whole preprocessed image can contain information for analysis. When set to `PSDM_CloseToImageSize`, the area for analysis is defined close to the original image size. **note: For correct operation of this property, the [`NoShadowsMode`](#noshadowsmode) property must be set to `false`.** #### `PaperSizeDetectionModeEnum` - `PSDM_Auto`: Determines the analysis area automatically. The area may be much smaller than the original image. - `PSDM_Unknown`: No predefined information about the image area. The analysis area may be much smaller than the original image. - `PSDM_CloseToImageSize`: The whole image can contain information for analysis. The analysis area stays close to the original image size. --- ### `DetectTextOnPictures` | Key | Type | Default | |------------------------|---------|---------| | `DetectTextOnPictures` | Boolean | `false` | When this property is set to `true`, the Pdftools OCR Service detects **all text** on a page image, including text embedded in pictures. The reading order isn't changed, enabling full-text search later. --- ### `DetectVerticalEuropeanText` | Key | Type | Default | |------------------------------|---------|---------| | `DetectVerticalEuropeanText` | Boolean | `false` | When set to `true`, the Pdftools OCR Service looks for vertically oriented text. It applies to all languages other than CJK. For CJK languages, vertical text detection is managed by the [`ProhibitCJKColumns`](#prohibitcjkcolumns) property. --- ### `ProhibitCJKColumns` | Key | Type | Default | |----------------------|---------|---------| | `ProhibitCJKColumns` | Boolean | `false` | The text in CJK languages can be written vertically as well as horizontally. Setting this property to `true` sets the Pdftools OCR Service to ignore the possibility of vertical text and recognize the image with the assumption that all text is arranged horizontally. This property is valid only for CJK languages. --- ### `ProhibitDoublePageMode` | Key | Type | Default | |--------------------------|---------|---------| | `ProhibitDoublePageMode` | Boolean | `false` | When set to `true`, the Pdftools OCR Service presumes that an image isn't a double-page book. --- ### `CollectPdfExportData` | Key | Type | Default | |------------------------|---------|---------| | `CollectPdfExportData` | Boolean | `false` | When set to `true`, the Pdftools OCR Service collects data for PDF export during layout analysis. The export process uses this data for image-only PDF with MRC compression. **note: With this property set to `true`, recognition isn't supported. Recognized text isn't needed to export the document to image-only PDF.** --- ## [PagePreprocessingParams] INI file section The `[PagePreprocessingParams]` INI file section defines configuration parameters for image preprocessing, including options for correcting image orientation, skew, geometry, resolution, binarization, and background whitening before text recognition. --- ## Orientation and skew correction ### `CorrectOrientationMode` | Key | Type | Default | |--------------------------|-------------------------------------------------------------|------------| | `CorrectOrientationMode` | [`CorrectOrientationModeEnum`](#correctorientationmodeenum) | `COM_Auto` | Specifies how image orientation should be corrected during preprocessing. In the default mode, orientation is determined and corrected automatically if needed. #### `CorrectOrientationModeEnum` - `COM_Auto`: Determines and corrects orientation automatically if needed. - `COM_Clockwise`: Rotates the image 90 degrees clockwise. - `COM_CounterClockwise`: Rotates the image 90 degrees counterclockwise. - `COM_UpsideDown`: Rotates the image 180 degrees. - `COM_No`: Don't correct orientation. --- ### `CorrectSkewMode` | Key | Type | Default | |-------------------|---------------------------------------------------|------------| | `CorrectSkewMode` | [`CorrectSkewModeEnum`](#correctskewmodeenum) | `CSM_Auto` | Specifies whether and how image skew should be corrected during page preprocessing. **note: Skew can be corrected only for angles not greater than 20 degrees.** #### `CorrectSkewModeEnum` - `CSM_Auto`: Uses neural-network-based skew correction. More accurate on average but slower than `CSM_Fast`. - `CSM_Fast`: Uses a non-neural-network skew correction algorithm. Faster but less precise on average. - `CSM_Off`: Disables skew correction. --- ### `StraightenLinesMode` | Key | Type | Default | |-----------------------|---------------------------------------------------------|------------| | `StraightenLinesMode` | [`StraightenLinesModeEnum`](#straightenlinesmodeenum) | `SLM_Auto` | Specifies how lines will be straightened during page preprocessing. In the default mode, a neural network algorithm is used. #### `StraightenLinesModeEnum` - `SLM_Auto`: Uses a neural-network-based method. Better average quality but slower than `SLM_Fast`. - `SLM_Fast`: Uses a non-neural-network method. Faster but lower average quality, though it may perform better on some pages. --- ## Image correction ### `CorrectInvertedImage` | Key | Type | Default | |------------------------|---------------------------------------------------------------|-------------| | `CorrectInvertedImage` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | Specifies if inverted images (white text on a black background) should be corrected. In the default mode, the Pdftools OCR Service corrects inverted images automatically. #### `ThreeStatePropertyValueEnum` - `TSPV_Auto`: Automatically determine if this processing mode should be used, depending on the situation (image characteristics, etc.). - `TSPV_No`: The processing mode in question will not be used. - `TSPV_Yes`: The processing mode in question will be used. --- ### `CorrectGeometry` | Key | Type | Default | |-------------------|---------------------------------------------------------------|-------------| | `CorrectGeometry` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | Specifies whether geometrical distortions (perspective on photos, curved lines from scanned books, and similar effects) should be removed during page preprocessing. In the default mode, the Pdftools OCR Service corrects geometry for photographs. --- ### `BackgroundWhitening` | Key | Type | Default | |-----------------------|---------------------------------------------------------------|-------------| | `BackgroundWhitening` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | Specifies if the image background should be whitened. In the default mode, the Pdftools OCR Service whitens the background automatically. --- ### `CropImage` | Key | Type | Default | |-------------|---------------------------------------------------------------|-------------| | `CropImage` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | If this property is set to `TSPV_Yes`, during preprocessing the Pdftools OCR Service detects document edges on the image and crops the image accordingly. In the default mode, the Pdftools OCR Service crops the image or skips this step automatically, depending on the source of the processed image. **note: This feature is not supported for black-and-white images.** --- ## Image type and resolution ### `DetectImageType` | Key | Type | Default | |-------------------|---------------------------------------------------------------|-------------| | `DetectImageType` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | Specifies how the image type is determined. This works in conjunction with the [`ImageSourceType`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/prepareimagemode#imagesourcetype) property of the `[PrepareImageMode]` section. - If `ImageSourceType` is `IST_Auto` and this property is `TSPV_Auto` or `TSPV_Yes`, the Pdftools OCR Service detects the image type automatically. - If `ImageSourceType` is `IST_Auto` and this property is `TSPV_No`, the image type is read from the file properties or metadata (faster, but depends on correct metadata). - If `ImageSourceType` is set to a specific value (for example `IST_Photo` or `IST_Scan`), detection is not performed regardless of this setting. --- ### `OverwriteResolutionMode` | Key | Type | Default | |---------------------------|---------------------------------------------------------------|------------| | `OverwriteResolutionMode` | [`OverwriteResolutionModeEnum`](#overwriteresolutionmodeenum) | `ORM_Auto` | Specifies whether the resolution of the image should be overwritten during page preprocessing. When set to `ORM_Manual`, use the [`ResolutionToOverwrite`](#resolutiontooverwrite) property to specify the new image resolution. The new resolution is applied before all other stages of image preparation (binarization, skew correction, and so on). **info: - If you set this property to `ORM_No` and the resolution of the prepared image is too low (less than 50 DPI), too high (more than 3200 DPI), or undefined, an error will occur.** - For PDF files, the resolution is used for image rasterization. The image size in pixels may change based on the detected resolution and page dimensions. #### `OverwriteResolutionModeEnum` - `ORM_Auto`: Automatically detects and overwrites the image resolution if needed. - `ORM_Manual`: Uses the resolution specified in the [`ResolutionToOverwrite`](#resolutiontooverwrite) property. - `ORM_No`: Don't overwrite the image resolution. --- ### `ResolutionToOverwrite` | Key | Type | Default | |-------------------------|-----------|---------| | `ResolutionToOverwrite` | `Integer` | `0` | Specifies the resolution value in DPI to overwrite the image resolution. This property is only used when [`OverwriteResolutionMode`](#overwriteresolutionmode) is set to `ORM_Manual`. **warning: The default value is `0`. You must set the desired resolution value when using `ORM_Manual`; otherwise, an error will occur.** --- ## Binarization and color ### `DiscardColorImage` | Key | Type | Default | |---------------------|-----------|---------| | `DiscardColorImage` | `Boolean` | `false` | When set to `true`, the Pdftools OCR Service leaves only the black-and-white plane in the prepared image. In this case, image binarization is performed during image preprocessing. --- ### `UseFastBinarization` | Key | Type | Default | |-----------------------|-----------|---------| | `UseFastBinarization` | `Boolean` | `false` | If this property is set to `true`, the Pdftools OCR Service uses algorithms for fast image binarization. This speeds up binarization, but quality may deteriorate. Binarization is performed either during preprocessing (if [`DiscardColorImage`](#discardcolorimage) is `true`), or later when a black-and-white image is necessary. --- ## Page splitting ### `SplitType` | Key | Type | Default | |-------------|-------------------------------------------|------------| | `SplitType` | [`PageSplitTypeEnum`](#pagesplittypeenum) | `PST_None` | Specifies the parameters of page splitting. #### `PageSplitTypeEnum` - `PST_None`: Don't split the page. - `PST_DoublePageSplit`: Splits a double-page spread into two separate pages. - `PST_BusinessCardSplit`: Splits a page containing multiple business cards into individual cards. --- ## [PageProcessingParams] INI file section The `[PageProcessingParams]` section is the central control point for the page-level pipeline. It covers three phases, each with a Boolean flag that enables or disables it: - **Preprocessing** ([`PerformPreprocessing`](#performpreprocessing)): corrects the page image (orientation, skew, geometry, resolution) before analysis. Fine-tuned in [`[PagePreprocessingParams]`](./pagepreprocessingparams.mdx). See also [`ProhibitColorObjectsAtProcessing`](#prohibitcolorobjectsatprocessing) for filtering color objects before analysis. - **Analysis** ([`PerformAnalysis`](#performanalysis)): detects layout structure and segments the page into blocks (text, tables, images, barcodes). Fine-tuned in [`[PageAnalysisParams]`](./pageanalysisparams.mdx). Object extraction is configured in [`[ObjectsExtractionParams]`](./objectsextractionparams.mdx). - **Recognition** ([`PerformRecognition`](#performrecognition)): reads text from detected blocks. Fine-tuned in [`[RecognizerParams]`](./recognizerparams.mdx). Page-level synthesis is configured in [`[SynthesisParamsForPage]`](./synthesisparamsforpage.mdx). If you disable a phase, its corresponding parameter section is ignored. --- ### `PerformPreprocessing` | Key | Type | Default | |-------------------------|-----------|---------| | `PerformPreprocessing` | `Boolean` | `true` | Specifies whether the engine corrects the page image before analysis. This step, called *preprocessing*, adjusts orientation, skew, geometry, resolution, and color inversion so that the image is ready for layout analysis and text recognition. If this property is `false`, the [`[PagePreprocessingParams]`](./pagepreprocessingparams.mdx) INI file section is ignored. --- ### `ProhibitColorObjectsAtProcessing` | Key | Type | Default | |-------------------------------------|-----------|---------| | `ProhibitColorObjectsAtProcessing` | `Boolean` | `false` | Specifies if color objects must be filtered out from the image before layout analysis and recognition. When set to `true`, Pdftools OCR Service removes color elements from the image so they don't interfere with text detection. --- ### `PerformAnalysis` | Key | Type | Default | |--------------------|-----------|---------| | `PerformAnalysis` | `Boolean` | `true` | Specifies if page analysis is to be performed. If this property is `false`, the [`[PageAnalysisParams]`](./pageanalysisparams.mdx) INI file section is ignored. --- ### `PerformRecognition` | Key | Type | Default | |----------------------|-----------|---------| | `PerformRecognition` | `Boolean` | `true` | Specifies if recognition is to be performed. If this property is `false`, the [`[RecognizerParams]`](./recognizerparams.mdx) INI file section is ignored. --- ## [PrepareImageMode] INI file section The `[PrepareImageMode]` configuration controls how images are prepared before OCR processing, including compression, document type classification, image source detection, and free text annotation handling. **info: Many image preprocessing settings that were previously part of `[PrepareImageMode]` (such as rotation, skew correction, resolution overwriting, binarization, contrast enhancement, and color inversion) have been moved to the [`[PagePreprocessingParams]`](./pagepreprocessingparams.mdx) section.** --- ### `CompressImageMode` | Key | Type | Default | |---------------------|---------------------------------------------------|------------| | `CompressImageMode` | [`CompressImageModeEnum`](#compressimagemodeenum) | `CIM_Auto` | Specifies if the image should be compressed during conversion to the internal format. This applies only to color and gray images; black-and-white images are always compressed with lossless compression. #### `CompressImageModeEnum` - `CIM_Auto`: Automatic mode. Born-digital images (for example, from PDF files) use lossless ZIP compression, while other images use JPEG compression. - `CIM_Lossless`: Use lossless ZIP compression for all images. - `CIM_MaxCompression`: Use JPEG compression for all images. --- ### `DocumentType` | Key | Type | Default | |----------------|-----------------------------------------|-----------| | `DocumentType` | [`DocumentTypeEnum`](#documenttypeenum) | `DT_Auto` | Specifies the type of the document on the image. If you know the document type for certain, you can set this property to bypass the document classifier and save processing time. #### `DocumentTypeEnum` - `DT_Auto`: Pdftools OCR Service runs the document classifier to determine the document type automatically. - `DT_BankCard`: The image contains a bank card. - `DT_Book`: The image contains a book page or multiple pages. - `DT_BusinessCard`: The image contains a business card. - `DT_DiscountCard`: The image contains a discount or loyalty card. - `DT_Document`: The image contains a single-page document. - `DT_Id`: The image contains an ID document. - `DT_NotDocument`: The image isn't a document (for example, a photograph without text). - `DT_Passport`: The image contains a passport double-page spread. - `DT_PassportPage`: The image contains a single passport page. - `DT_Receipt`: The image contains a receipt. - `DT_TechnicalDrawing`: The image contains an engineering diagram or technical drawing. - `DT_Unknown`: Reserved for internal use. --- ### `ImageSourceType` | Key | Type | Default | |-------------------|-------------------------------------------------|------------| | `ImageSourceType` | [`ImageSourceTypeEnum`](#imagesourcetypeenum) | `IST_Auto` | Specifies the image origin. Different image sources (for example, a photo versus a screenshot) require different preprocessing techniques. #### `ImageSourceTypeEnum` - `IST_Auto`: Pdftools OCR Service detects the image origin automatically. - `IST_Photo`: The image is a photograph. - `IST_Scan`: The image is a scanned document. - `IST_Screenshot`: The image is a screenshot. - `IST_SyntheticImage`: The image contains text produced by rasterizing digital fonts. For example, a born-digital image-only PDF document. - `IST_SyntheticText`: The image contains a text layer. For example, a born-digital PDF document with an embedded text layer. --- ### `RasterizeFreeText` | Key | Type | Default | |---------------------|-----------|---------| | `RasterizeFreeText` | `Boolean` | `true` | Specifies whether Free Text annotations from the input PDF document should be retained. When set to `true`, the Pdftools OCR Service rasterizes free text annotations so they become part of the image content. --- ## [RecognizerParams] INI file section The `[RecognizerParams]` INI file section includes settings for controlling language, text types, performance, and fine-tuning options used by the Pdftools OCR Service during text recognition. --- ## Main settings ### `TextLanguage` | Key | Type | Default | |----------------|----------------|-----------| | `TextLanguage` | `TextLanguage` | `English` | The languages used for text recognition are separated by commas. The supported languages are listed in the [Supported languages](https://www.pdf-tools.com/docs/ocr-service/references/ocr-languages) page. --- ### `LanguageDetectionMode` | Key | Type | Default | |-------------------------|---------------------------------------------------------------|-------------| | `LanguageDetectionMode` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | Controls automatic language detection. With autodetection enabled, Pdftools OCR Service identifies the language of each word from the languages specified in the [TextLanguage](#textlanguage) property. This is useful for documents whose language you don't know in advance. If all specified languages are present in the document, autodetection isn't needed—set this property to `TSPV_No` to turn it off. #### `ThreeStatePropertyValueEnum` - `TSPV_Auto`: Automatically determine if this processing mode should be used, depending on the situation (image characteristics, etc.). - `TSPV_No`: The processing mode in question will not be used. - `TSPV_Yes`: The processing mode in question will be used. --- ### `TextTypes` | Key | Type | Default | |-------------|---------------------------------|-------------| | `TextTypes` | [`TextTypeEnum`](#texttypeenum) | `TT_Normal` | Set this property to one or more `TextTypeEnum` values combined with the OR operator to specify which text types to recognize. For example, `TT_Normal | TT_Index` limits recognition to standard typographic text and ZIP-code-style digits. **info: - If this property is equal to any combination of `TT_Matrix`, `TT_Typewriter`, `TT_OCR_A`, and `TT_OCR_B`, italic fonts and superscript/subscript aren't recognized, regardless of the values of the [`ProhibitItalic`](#prohibititalic), [`ProhibitSubscript`](#prohibitsubscript) and [`ProhibitSuperscript`](#prohibitsuperscript) properties.** - If this property is `TT_Handwritten`, the image orientation cannot be corrected. #### `TextTypeEnum` - `TT_Gothic`: Text printed in Gothic (Fraktur) typeface. - `TT_Handwritten`: Handwritten and handprinted text. :::note Automatic analysis isn't available for handwritten text. Set the coordinates of blocks containing handwritten text manually. ::: - `TT_Index`: A digit-only character set for text written in ZIP-code style. - `TT_Matrix`: Text printed on a dot-matrix printer. - `TT_MICR_CMC7`: A character set for digits and the letters A–E in the CMC-7 Magnetic Ink Character Recognition (MICR) barcode font. Only supported for Latin-based languages. - `TT_MICR_E13B`: A character set for digits and the symbols A–D printed in magnetic ink (E13B font), commonly used on personal checks and banking documents. Only supported for Latin-based languages. - `TT_Normal`: Standard typographic text. This is the default text type. - `TT_OCR_A`: A monospaced font designed for optical character recognition, commonly used in banking and credit card processing. - `TT_OCR_B`: A font optimized for optical character recognition. - `TT_Receipt`: Optimized for sales receipts and invoices. Rather than targeting a specific font, this type signals that the input may contain low-quality text in monospaced or normal font. - `TT_Typewriter`: Text typed on a typewriter. --- ### `DetectTextTypesIndependently` | Key | Type | Default | |--------------------------------|-----------|---------| | `DetectTextTypesIndependently` | `Boolean` | `false` | When enabled, Pdftools OCR Service determines the text type for each block independently. This helps with documents containing small blocks of different text types, though it may slightly slow down processing. --- ## Recognition speed ### `Mode` | Key | Type | Default | |--------|-------------------------------------------------|-------------| | `Mode` | [`RecognitionModeEnum`](#recognitionmodeenum) | `RM_Normal` | Sets the recognition mode, which controls the balance between speed and accuracy during processing. **info: Built-in patterns are always used for the accurate mode. To disable using the built-in patterns, switch to the normal mode (`RM_Normal`).** #### `RecognitionModeEnum` - `RM_Fast`: Provides maximum recognition speed with a moderately increased error rate. On high-quality text, this typically results in 1–2 errors per page. - `RM_Normal`: An intermediate mode between fast and accurate. Provides satisfying recognition results on noisy images or documents with complex layouts. - `RM_Accurate`: Provides maximum accuracy on poor-quality documents and images using advanced neural network technologies. Slower than the other modes. --- ## Fine tuning ### `LowResolutionMode` | Key | Type | Default | |---------------------|-----------|---------| | `LowResolutionMode` | `Boolean` | `false` | Enables recognition of text from low-resolution images. Use this for faxes, small prints, or documents with poor print quality. --- ### `OneLinePerBlock` | Key | Type | Default | |-------------------|-----------|---------| | `OneLinePerBlock` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service treats each text block as containing a single line of text. --- ### `OneWordPerLine` | Key | Type | Default | |------------------|-----------|---------| | `OneWordPerLine` | `Boolean` | `false` | When set to `true`, each line of text is treated as a single word during recognition. --- ### `ProhibitItalic` | Key | Type | Default | |------------------|-----------|---------| | `ProhibitItalic` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service does **not** recognize letters printed with an italic-style font. It's useful when a text with presumably no italic letters is recognized, in which case it may speed up recognition. If there are any italic letters on the image, and this property is `true`, these letters are recognized incorrectly. --- ### `ProhibitSubscript` | Key | Type | Default | |---------------------|-----------|---------| | `ProhibitSubscript` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service does **not** recognize subscript letters. It's useful when a text with presumably no subscripts is recognized, in which case it may speed up recognition. If there are any subscript letters on the image, and this property is `true`, these letters are recognized incorrectly. --- ### `ProhibitSuperscript` | Key | Type | Default | |-----------------------|-----------|---------| | `ProhibitSuperscript` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service does **not** recognize superscript letters. It's useful when a text with presumably no superscripts is recognized, in which case it may speed up recognition. If there are any superscript letters on the image, and this property is `true`, these letters are recognized incorrectly. --- ### `ProhibitSmallCaps` | Key | Type | Default | |---------------------|-----------|---------| | `ProhibitSmallCaps` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service does **not** recognize small capital letters. --- ### `ProhibitHyphenation` | Key | Type | Default | |-----------------------|-----------|---------| | `ProhibitHyphenation` | `Boolean` | `false` | When set to `true`, prohibits recognition of hyphenation from line to line. It's useful when a text with presumably no hyphenations is recognized, in which case it may speed up recognition. If there are any hyphenations in the recognized block, and this property is `true`, the hyphenated words are recognized incorrectly. --- ### `ProhibitInterblockHyphenation` | Key | Type | Default | |---------------------------------|-----------|---------| | `ProhibitInterblockHyphenation` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service presumes that text from one block can't be carried over to the next block. --- ### `CaseRecognitionMode` | Key | Type | Default | |-----------------------|-------------------------------------------------------|----------------| | `CaseRecognitionMode` | [`CaseRecognitionModeEnum`](#caserecognitionmodeenum) | `CRM_AutoCase` | Controls how letter case (uppercase/lowercase) is handled in the recognized output. #### `CaseRecognitionModeEnum` - `CRM_AutoCase`: Automatically detects the case of letters and keeps it in the output text. - `CRM_CapitalCase`: Sets the recognized text to capitals. - `CRM_SmallCase`: Sets the recognized text to lowercase. --- ## Handprint recognition ### `FieldMarkingType` | Key | Type | Default | |--------------------|-------------------------------------------------|------------------| | `FieldMarkingType` | [`FieldMarkingTypeEnum`](#fieldmarkingtypeenum) | `FMT_SimpleText` | Defines the type of field marking around handprinted characters, such as underlines, frames, or boxes. This property applies only to handprint recognition. **info: For correct handprint recognition, use the [`CellsCount`](#cellscount) property that allows** you to set the number of character cells for a recognized block. #### `FieldMarkingTypeEnum` - `FMT_CharBoxSeries`: Each character is in a separate box. - `FMT_CombInFrame`: Characters are in a comb layout that also serves as the bottom line of a frame. - `FMT_GrayBoxes`: Characters are in white fields on a gray background. - `FMT_PartitionedFrame`: Characters are in a frame divided by vertical lines. - `FMT_SimpleComb`: Characters are in a comb layout. - `FMT_SimpleText`: Plain text with no marking. - `FMT_TextInFrame`: The text is enclosed in a frame. - `FMT_UnderlinedText`: The text is underlined. --- ### `CellsCount` | Key | Type | Default | |--------------|-----------|---------| | `CellsCount` | `Integer` | `1` | Sets the number of character cells in a handprint block. This property applies only to [`FieldMarkingType`](#fieldmarkingtype) values that divide text into individual cells. The default is `1`, but you should set the correct value for your document to get accurate recognition results. --- ## User patterns ### `UseBuiltInPatterns` | Key | Type | Default | |----------------------|-----------|---------| | `UseBuiltInPatterns` | `Boolean` | `true` | When set to `true`, Pdftools OCR Service uses its own built-in patterns for recognition. Patterns are files that establish a relationship between the character image and the character itself. Set this property to `false` when you don't want to use standard Pdftools OCR Service patterns for character recognition, but user patterns only. This can be useful for recognizing text typed with decorative or nonstandard fonts. In this case, don't use Pdftools OCR Service built-in patterns but instead use your own user-defined patterns trained for these fonts. A path to a user-defined pattern file is stored in the [`UserPatternsFile`](#userpatternsfile) property. If the [`UserPatternsFile`](#userpatternsfile) property is empty, the [`UseBuiltInPatterns`](#usebuiltinpatterns) property is ignored. **info: You can set this property to `false` when using the normal and fast recognition modes. You can't prohibit using the built-in patterns for the accurate mode.** --- ### `UserPatternsFile` | Key | Type | Default | |--------------------|----------|---------| | `UserPatternsFile` | `String` | `""` | Contains the full path to a file with the user pattern used for recognition. If the value of this property isn't empty, information from the user pattern file is used during recognition. If the [`UseBuiltInPatterns`](#usebuiltinpatterns) property is `false`, meaning that standard Pdftools OCR Service patterns aren't used during recognition, this property should contain a path to a user-defined pattern file, as only information stored in it is used. --- ## [SortingBlocksParams] INI file section The `[SortingBlocksParams]` INI file section controls how [layout blocks](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/pageanalysisparams#block-detection) are grouped by proximity when determining reading order. Blocks are sorted by position (left to right, then top to bottom) and blocks that are spatially close together are treated as part of the same logical group. --- ### `Gap` | Key | Type | Default | |-------|-----------|---------| | `Gap` | `Integer` | `0` | Sets the maximum allowed distance between two adjacent blocks for them to be treated as part of the same logical group. If the distance between two blocks exceeds this value, they belong to separate groups. The default value of `0` means no additional grouping is applied beyond the default sorting order. --- ### `GapMeasurementUnit` | Key | Type | Default | |----------------------|---------------------------------------------------------|--------------------------------| | `GapMeasurementUnit` | [`GapMeasurementUnitEnum`](#gapmeasurementunitenum) | `GMU_PercentOfMinimumFontSize` | Defines the unit used to measure the distance between blocks when evaluating the `Gap` threshold. #### `GapMeasurementUnitEnum` - `GMU_Pixel`: The gap is measured in pixels. - `GMU_PercentOfMinimumFontSize`: The gap is measured as a percentage of the minimum font size of the text in two adjacent blocks. - `GMU_Twip`: The gap is measured in twips (1/1440 of an inch). --- ## [SynthesisParamsForDocument] INI file section The `[SynthesisParamsForDocument]` INI file section controls document synthesis, including structure detection, font formatting, and memory optimization during OCR processing. --- ## Main settings ### `DetectDocumentStructure` | Key | Type | Default | |---------------------------|-----------|---------| | `DetectDocumentStructure` | `Boolean` | `true` | Controls whether Pdftools OCR Service analyzes the logical structure of the document (headings, table of contents, lists) during synthesis. When set to `true`, the [`[DocumentStructureDetectionParams]`](./documentstructuredetectionparams.mdx) section provides additional configuration options for structure detection. --- ### `DetectFontFormatting` | Key | Type | Default | |------------------------|-----------|---------| | `DetectFontFormatting` | `Boolean` | `true` | Controls whether Pdftools OCR Service identifies font formatting (bold, italic, font size) during document synthesis. When set to `false`, the [`[FontFormattingDetectionParams]`](./fontformattingdetectionparams.mdx) section has no effect. **info: By default, font formatting is detected at the document synthesis stage. If you turn off this property, you must turn on font detection during page synthesis instead by setting [`DetectFontFormattingAtPageLevel`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/synthesisparamsforpage#detectfontformattingatpagelevel) to `true` in [`[SynthesisParamsForPage]`](./synthesisparamsforpage.mdx).** Moving font detection to page synthesis can reduce processing time and memory consumption during document synthesis, but may produce less accurate formatting results. --- ## Additional settings ### `LowMemoryMode` | Key | Type | Default | |-----------------|-----------|---------| | `LowMemoryMode` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service limits memory consumption to about 600 MB during document synthesis by reducing the number of pages held in memory at once. This can slow down processing and slightly reduce output quality. --- ### `PagePoolSize` | Key | Type | Default | |----------------|-----------|---------| | `PagePoolSize` | `Integer` | `64` | Sets the maximum number of pages that Pdftools OCR Service holds in memory during document synthesis. Increasing this value improves processing speed, while lowering it reduces memory usage. A range of 32–64 works well for most documents. For large documents, avoid setting this too high to prevent out-of-memory errors. Values under 5 have no effect. --- ## [SynthesisParamsForPage] INI file section The `[SynthesisParamsForPage]` INI file section defines page-level synthesis settings for paragraph structure, font formatting, link detection, and color detection. --- ## Main settings ### `ParagraphExtractionMode` | Key | Type | Default | |---------------------------|---------------------------------------------------------------|------------------------| | `ParagraphExtractionMode` | [`ParagraphExtractionModeEnum`](#paragraphextractionmodeenum) | `PEM_NormalExtraction` | Controls how paragraphs are identified and extracted from recognized text. #### `ParagraphExtractionModeEnum` - `PEM_NormalExtraction`: Standard paragraph detection and extraction. - `PEM_RoughExtraction`: Produces the fewest paragraphs possible—either one per block or only those beginning with an enlarged initial letter (drop cap). - `PEM_SingleLineParagraphsWithSpaceFormatting`: Treats each line as its own paragraph, preserving space-based formatting. - `PEM_SingleLineParagraphsWithWordSeparationOnly`: Treats each line as its own paragraph, using spaces only to separate words without additional formatting. --- ### `DetectFontFormattingAtPageLevel` | Key | Type | Default | |----------------------------------|-----------|---------| | `DetectFontFormattingAtPageLevel` | `Boolean` | `false` | When set to `true`, font formatting—including subscripts, superscripts, italics, and small caps—is identified during page synthesis rather than document synthesis. This also activates the [`[FontFormattingDetectionParams]`](./fontformattingdetectionparams.mdx) section, which provides additional control over formatting detection. When this property is `false`, [`[FontFormattingDetectionParams]`](./fontformattingdetectionparams.mdx) has no effect. **info: By default, Pdftools OCR Service identifies font formatting at the document synthesis stage. If you set this property to `true`, you must turn off formatting detection during document synthesis by setting [`DetectFontFormatting`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/synthesisparamsfordocument#detectfontformatting) to `false`.** Moving font detection to page synthesis can reduce processing time and memory consumption during document synthesis, but may produce less accurate formatting results. --- ### `DetectDocumentLinks` | Key | Type | Default | |------------------------|-----------|---------| | `DetectDocumentLinks` | `Boolean` | `true` | When set to `true`, Pdftools OCR Service identifies internal document references such as cross-references during page synthesis. --- ### `DetectHyperlinks` | Key | Type | Default | |--------------------|-----------|---------| | `DetectHyperlinks` | `Boolean` | `true` | When set to `true`, Pdftools OCR Service identifies hyperlinks (URLs, email addresses) in recognized text during page synthesis. --- ### `SynthesizeBusinessCards` | Key | Type | Default | |---------------------------|-----------|---------| | `SynthesizeBusinessCards` | `Boolean` | `false` | When set to `true`, Pdftools OCR Service attempts to find and process business cards on the page. --- ## Color settings ### `DetectBackgroundColor` | Key | Type | Default | |-------------------------|---------------------------------------------------------------|-------------| | `DetectBackgroundColor` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | When set to `TSPV_Yes`, Pdftools OCR Service identifies background colors during page synthesis. #### `ThreeStatePropertyValueEnum` - `TSPV_Auto`: Automatically determine if this processing mode should be used, depending on the situation (image characteristics, etc.). - `TSPV_No`: The processing mode in question will not be used. - `TSPV_Yes`: The processing mode in question will be used. --- ### `AllowGrayBackgroundColor` | Key | Type | Default | |----------------------------|---------------------------------------------------------------|-------------| | `AllowGrayBackgroundColor` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | When set to `TSPV_Yes`, gray shades are included in background color detection. Otherwise, backgrounds are classified as either black or white. This property only applies when [`DetectBackgroundColor`](#detectbackgroundcolor) is set to `TSPV_Yes` or `TSPV_Auto`. --- ### `DetectTextColor` | Key | Type | Default | |-------------------|---------------------------------------------------------------|-------------| | `DetectTextColor` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | When set to `TSPV_Yes`, Pdftools OCR Service identifies text colors during page synthesis. --- ### `AllowGrayTextColor` | Key | Type | Default | |----------------------|---------------------------------------------------------------|-------------| | `AllowGrayTextColor` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | When set to `TSPV_Yes`, gray shades are included in text color detection. Otherwise, text is classified as either black or white. This property only applies when [`DetectTextColor`](#detecttextcolor) is set to `TSPV_Yes` or `TSPV_Auto`. --- ### `CorrectDynamicRange` | Key | Type | Default | |-----------------------|---------------------------------------------------------------|-------------| | `CorrectDynamicRange` | [`ThreeStatePropertyValueEnum`](#threestatepropertyvalueenum) | `TSPV_Auto` | When set to `TSPV_Yes`, image colors are adjusted to maximize contrast between text and background (for example, making the background white and text black, or the reverse). This improves image quality but increases processing time. This property is most effective when [`DetectBackgroundColor`](#detectbackgroundcolor) and [`DetectTextColor`](#detecttextcolor) are set to `TSPV_Yes` or `TSPV_Auto`. --- ## [TableAnalysisParams] INI file section The `[TableAnalysisParams]` INI file section defines parameters that control how the Pdftools OCR Service analyzes table structures. These parameters are only used when the [`DetectTables`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/pageanalysisparams#detecttables) property in the `[PageAnalysisParams]` section is set to `true`. --- ### `DetectCellsInversion` | Key | Type | Default | |------------------------|---------|---------| | `DetectCellsInversion` | Boolean | `true` | If this property is `true`, cell inversion is detected during table block analysis. --- ### `DetectCellsOrientation` | Key | Type | Default | |--------------------------|---------|---------| | `DetectCellsOrientation` | Boolean | `true` | If this property is `true`, cell orientation is detected during table block analysis. --- ### `SingleLinePerCell` | Key | Type | Default | |---------------------|---------|---------| | `SingleLinePerCell` | Boolean | `false` | Set this property to `true` if the tables you're processing contain only one line of text per cell. This enables faster and more accurate table layout analysis. --- ### `SplitOnlyBySeparators` | Key | Type | Default | |-------------------------|---------|---------| | `SplitOnlyBySeparators` | Boolean | `false` | Set this property to `true` if the tables you're processing have no hidden separators. This enables faster and more accurate table layout analysis. --- ## [TextLayerInjectionParams] INI file section The `[TextLayerInjectionParams]` INI file section defines parameters for creating a searchable PDF with text layer injection, including PDF/A compliance and image correction settings. --- ### `PerformRecognition` | Key | Type | Default | |----------------------|-----------|---------| | `PerformRecognition` | `Boolean` | `true` | Specifies whether document processing should be performed during text layer injection. If this property is `false`, the original document is converted without text layer injection. --- ### `PDFAComplianceMode` | Key | Type | Default | |-----------------------|-----------------------------------------------------------|------------| | `PDFAComplianceMode` | [`PDFAComplianceModeEnum`](#pdfacompliancemodeenum) | `PCM_None` | Specifies the PDF/A standard compliance for the output PDF file. The default value `PCM_None` means that the output file inherits the PDF/A standard compliance from the original document. #### `PDFAComplianceModeEnum` - `PCM_None`: The output file inherits the PDF/A standard compliance from the original document. - `PCM_Pdfa_1a`: PDF/A-1a compliance. - `PCM_Pdfa_1b`: PDF/A-1b compliance. - `PCM_Pdfa_2a`: PDF/A-2a compliance. - `PCM_Pdfa_2b`: PDF/A-2b compliance. - `PCM_Pdfa_2u`: PDF/A-2u compliance. - `PCM_Pdfa_3a`: PDF/A-3a compliance. - `PCM_Pdfa_3b`: PDF/A-3b compliance. - `PCM_Pdfa_3u`: PDF/A-3u compliance. --- ### `AllowChangePDFAView` | Key | Type | Default | |------------------------|-----------|---------| | `AllowChangePDFAView` | `Boolean` | `false` | Specifies whether to change the appearance of the output PDF file in case of problems during its processing. When set to `false`, document processing is canceled whenever the document is invalid. If this property is `true`, a warning about changing the appearance of the output is issued instead. --- ### `WriteCorrectedImage` | Key | Type | Default | |------------------------|-----------|---------| | `WriteCorrectedImage` | `Boolean` | `false` | Specifies if skew and orientation correction should be performed on the original document. When this property is set to `true`, the final document contains the corrected image. **note: This property is available only if the [`CorrectOrientationMode`](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/pagepreprocessingparams#correctorientationmode) property of the `[PagePreprocessingParams]` section isn't set to `COM_No`. Otherwise, skew and orientation aren't corrected.** --- ### `WriteTaggedPDF` | Key | Type | Default | |------------------|-----------|---------| | `WriteTaggedPDF` | `Boolean` | `false` | Specifies if the resulting PDF document should be tagged. Tagging a PDF embeds structural information that enables text reflow, conversion to formats like HTML and XML, and improved accessibility. **info: This property must be set to `true` if the [`PDFAComplianceMode`](#pdfacompliancemode) property is set to `PCM_Pdfa_1a`, `PCM_Pdfa_2a`, or `PCM_Pdfa_3a`, because PDF/A-1a, PDF/A-2a, and PDF/A-3a are always tagged. If the source PDF is tagged, the value of this property is ignored, and the resulting PDF file is always tagged.** --- ## Pdftools OCR Service release notes Learn about new updates in the OCR Service, including new features, improvements, and bug fixes. ## Version 1.1.1 8 March 2026 ### Fixed - Before this update, an internal licensing operation could fail silently in certain Licensing Gateway Service (LGS) configurations. With this update, the issue is resolved and licensing works as expected in all supported setups. ## Version 1.1.0 6 March 2026 ### Added - Docker container support for Pdftools OCR Service. With this release, the Manager and Worker nodes can be deployed as Docker containers. For more details, review [OCR Service in Docker](https://www.pdf-tools.com/docs/ocr-service/getting-started/docker). - Added support for multiple OCR languages: Arabic, Chinese, Hebrew, Japanese, Korean, and Thai. :::info[Additional language support] Before you use Arabic, Chinese, Hebrew, Japanese, Korean, or Thai in OCR analysis, contact us through the **[Contact page](https://www.pdf-tools.com/contact/)** for exact pricing information. OCR analysis of these languages has **additional costs**. ::: - Added predefined profiles: `DataExtraction`, `DocumentConversion_Normal`, `HighCompressedImageOnlyPdf`, `BusinessCardsProcessing`, and `MachineReadableZone`. For details on each profile, review [Predefined profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/). - Added INI file sections for custom profiles: - [`[DocumentStructureDetectionParams]`](./references/parameters/custom-profiles/documentstructuredetectionparams.mdx) for configuring headline, footnote, caption, column, list, and table of contents detection. - [`[SortingBlocksParams]`](./references/parameters/custom-profiles/sortingblocksparams.mdx) for controlling how Pdftools OCR Service combines recognized text blocks into groups. - [`[TextLayerInjectionParams]`](./references/parameters/custom-profiles/textlayerinjectionparams.mdx) for configuring searchable PDF creation with text layer injection. - Persistent connections with automatic retry and reconnect logic for interservice communication between processes within a Worker node. Worker service processes maintain long-lived connections instead of establishing a new connection for each request, reducing connection overhead. ### Changed - Removed predefined profiles: - `DocumentConversion_Speed` - `BookArchiving_Accuracy` - `BookArchiving_Speed` - All predefined OCR profiles use updated parameter names and settings. If you use custom profiles that reference or extend predefined profiles, review and update your configurations after upgrading. For details, review [Predefined profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/) and the following section [Parameter changes by INI file section](#parameter-changes-by-ini-file-section). #### Parameter changes by INI file section The following sections describe changed, moved, and removed parameters in each INI file section. ##### `[PrepareImageMode]` The following parameters moved to other INI file sections or have new replacements: | Removed `[PrepareImageMode]` parameters | Replacement | |------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Rotation` | Use `RotationType` in [`[ImageProcessingParams]`](./references/parameters/custom-profiles/imageprocessingparams.mdx) | | `InvertImage`, `MirrorImage` | Moved to [`[ImageProcessingParams]`](./references/parameters/custom-profiles/imageprocessingparams.mdx) | | `CorrectSkew`, `CorrectSkewMode` | Use `CorrectSkewMode` in [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) | | `AutoOverwriteResolution`, `OverwriteResolution`, `XResolutionToOverwrite`, `YResolutionToOverwrite` | Use `OverwriteResolutionMode` and `ResolutionToOverwrite` in [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) | | `DiscardColorImage`, `UseFastBinarization` | Moved to [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) | | `EnhanceLocalContrast` | Use `BackgroundWhitening` in [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) | | `PhotoProcessingMode` | Use `ImageSourceType` in [`[PrepareImageMode]`](./references/parameters/custom-profiles/prepareimagemode.mdx) and `DetectImageType` in [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) | | `ImageCompression` | Use `CompressImageMode` in [`[PrepareImageMode]`](./references/parameters/custom-profiles/prepareimagemode.mdx) | | `BackgroundFillingColor`, `CreatePreview`, `PreviewHeight`, `PreviewWidth` | Removed with no replacement | New `[PrepareImageMode]` parameters: - `CompressImageMode` - `DocumentType` - `ImageSourceType` - `RasterizeFreeText` ##### `[PagePreprocessingParams]` | Removed `[PagePreprocessingParams]` parameters | Replacement | |-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | `CorrectOrientation` (Boolean) | `CorrectOrientationMode` (enum: `COM_Auto`, `COM_Clockwise`, `COM_CounterClockwise`, `COM_UpsideDown`, `COM_No`) | | `CorrectShadowsAndHighlights` | Removed with no replacement | | `CorrectSkew` + `CorrectSkewMode` (6-value flag enum) | Single `CorrectSkewMode` with new enum values: `CSM_Auto`, `CSM_Fast`, `CSM_Off` | | `GeometryCorrectionMode` | `CorrectGeometry` (`ThreeStatePropertyValueEnum`) | | `ResolutionCorrectionMode` | `OverwriteResolutionMode` and `ResolutionToOverwrite` | - Type change: `CorrectInvertedImage` changed from `Boolean` (default `false`) to `ThreeStatePropertyValueEnum` (default `TSPV_Auto`) - New `[PagePreprocessingParams]` parameters: - `StraightenLinesMode` - `BackgroundWhitening` - `CropImage` - `DetectImageType` - `DiscardColorImage` - `UseFastBinarization` - `SplitType` - `OverwriteResolutionMode` - `ResolutionToOverwrite` ##### `[PageAnalysisParams]` Removed `[PageAnalysisParams]` parameters: - `EnableTextExtractionMode`: replaced with `AnalysisMode` (set to `PAM_TextExtraction`). - `AggressiveTableDetection`: Removed with no replacement - `DetectMultipleBusinessCards`: Removed with no replacement - `ProhibitModelAnalysis`: Removed with no replacement New `[PageAnalysisParams]` parameters: - `AnalysisMode` - `SpeedQualityMode` - `DetectHandwritten` - `DetectCheckmarks` - `DetectStamps` - `PaperSizeDetectionMode` - `DetectTextOnPictures` (moved from `[ObjectsExtractionParams]`) - `CollectPdfExportData` ##### `[RecognizerParams]` Removed `[RecognizerParams]` parameters: - `BalancedMode` (Boolean): Replaced with `Mode` (set to `RM_Normal`) - `FastMode` (Boolean): Replaced with `Mode` (set to `RM_Fast`) - `WritingStyle` (all `WS_*` values): Removed with no replacement Enum rename: - `TT_Handprinted` renamed to `TT_Handwritten` in `TextTypeEnum`. New `[RecognizerParams]` parameters: - `Mode` - `DetectTextTypesIndependently` - `ProhibitSmallCaps` ##### `[BarcodeParams]` | Change | Details | |-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Removed `[BarcodeParams]` parameters | `MinRatioToTextHeight`, `EnableAdvancedExtractionMode`, `IsCode39WithoutAsterisk` | | New parameter | `EnableBarcodesCheck` | | New `BarcodeTypeEnum` values | `BT_AutodetectWithoutPostal`, `BT_Australia4State`, `BT_JapanPost`, `BT_KIX`, `BT_RoyalMail4State` | | Removed `BarcodeSupplementTypeEnum` value | `BS_Unknown` | | New `CodePageEnum` values for added languages | `CP_Hebrew`, `CP_Hebrew_ISO`, `CP_Hebrew_Macintosh`, `CP_Hebrew_MSDOS`, `CP_Japan_Mac`, `CP_Japan_SJIS`, `CP_Korean`, `CP_Korean_Johab`, `CP_Korean_Mac`, `CP_Thai`, `CP_Thai_Macintosh` | ##### `[FontFormattingDetectionParams]` - Moved parameter: `DetectDropCaps` moved to [`[PageAnalysisParams]`](./references/parameters/custom-profiles/pageanalysisparams.mdx). - Default change: `DetectSpacing` default changed from `true` to `false`. ##### `[ObjectsExtractionParams]` - Moved parameter: `DetectTextOnPictures` moved to [`[PageAnalysisParams]`](./references/parameters/custom-profiles/pageanalysisparams.mdx). - New `[ObjectsExtractionParams]` parameter: `SourceContentReuseMode`. ##### `[SynthesisParamsForPage]` New `[SynthesisParamsForPage]` parameters: - `DetectDocumentLinks` - `DetectHyperlinks` - `SynthesizeBusinessCards` - `AllowGrayTextColor` ##### Removed `[OrientationDetectionParams]` - The `[OrientationDetectionParams]` INI file section was removed. Use `CorrectOrientationMode` in [`[PagePreprocessingParams]`](./references/parameters/custom-profiles/pagepreprocessingparams.mdx) instead. ### Fixed - Before this update, Worker service processes established a new connection to the main Worker service for each request. In rare cases, a race condition during connection setup caused request failures. With this update, persistent connections with automatic reconnect logic resolve this issue. ## Version 1.0.2 10 November 2025 ### Fixed - Fixed SDK corruption issues with ABBYY FineReader Engine that could cause the Pdftools OCR Service to become unstable or crash during processing. As of this update, the service automatically detects corruption and recreates the OCR engine when needed. - Fixed failures when processing large files by increasing the default maximum request body size from 30 MB to 100 MB. As a result, processing of large TIFF files and multi-page documents no longer fails due to file size limitations. - Improved error handling and logging for failed OCR jobs, with better exception tracking and proper error code reporting. ### Changed - The maximum request body size is now configurable using the `MaxRequestBodySizeBytes` setting in the manager node `appsettings.json` file, allowing administrators to adjust the limit based on their specific requirements. The configured default is 100 MB (specifically, it is defined as 104857600 bytes). ## Version 1.0.1 15 September 2025 ### Fixed - Fixed PostgreSQL database migration compatibility issues to ensure correct schema updates when upgrading from previous versions. - Improved OCR validation and file creation processes to enhance reliability and error handling during document processing. ## Version 1.0.0 30 July 2025 ### Added - First release of the Pdftools OCR Service introduces a new OCR engine that is fully compatible with current 3-Heights® OCR Service workflows and configurations. It acts as a drop-in replacement for existing installations, requiring no changes to your integration or processing pipelines. Compared to the previous OCR configurations (the ABBYY FineReader using your license key and the legacy 3-Heights® OCR Service), the new Pdftools OCR Service also provides: - Streamlined installation and license key configuration. - Scalability options to support higher throughput. ### Changed - Compared to the 3-Heights® OCR Service, this release of the Pdftools OCR Service doesn't include support for the `BusinessCardsProcessing` predefined OCR profile. --- ## Pdftools SDK overview The Pdftools SDK lets you build software that processes PDFs at a large scale. The SDK is delivered as a high-performance native library and works with C, .NET, C#, Java, and Python, letting the developers embed PDF functionality into backend systems, desktop apps, and server-side automation. The SDK consolidates fundamental PDF processing pipelines, such as PDF/A conversion, optimization, document assembly, and PDF-to-image or image-to-PDF workflows, into one single high-level API that developers integrate directly into their applications. The Pdftools SDK is made for engineering teams that need: - **Explicit control** over document processing steps - **Stable interfaces** across platforms and languages - **Custom workflow implementation** for archiving, compression, conversion, signature services, and much more - **Large-scale document processing** systems - **High-performance** native libraries with a small **memory footprint** and **predictable runtime behavior** ## What the Pdftools SDK doesn't include The Pdftools SDK is focused on fundamental PDF processing pipelines and doesn't include: - Viewer components. Review the [PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer) for viewing features. - Job orchestration, distribution for scaling, UI or low-code-driven document processing pipelines. Check out the [Conversion Service](https://www.pdf-tools.com/docs/conversion-service) instead. - Low-level PDF manipulation such as creating new PDFs, setting metadata, and editing PDF content. Use the [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on) instead. - Intelligent Document Processing (IDP) and other machine learning document intelligence features. --- ## API references and technical notes Learn about available API references and explore technical notes. ## API references - [C API](https://api-reference.pdf-tools.com/pdfsdk/1.17/cdoc/files.html) - [Java API](https://api-reference.pdf-tools.com/pdfsdk/1.17/javadoc/index.html) - [.NET API](https://api-reference.pdf-tools.com/pdfsdk/1.17/dotnet/html/R_Project_API_Reference.htm) - [Python API](https://api-reference.pdf-tools.com/pdfsdk/1.17/pydocs/index.html) ## Technical notes Find an overview of the technical details about the Pdftools SDK for various programming languages on the [Technical notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/) overview page. --- ## Technical notes --- ## C technical notes Learn about the specifics and technical details of the Pdftools SDK for C. **tip: For the full API reference for the Pdftools SDK, see the [C API reference](https://api-reference.pdf-tools.com/pdfsdk/1.17/cdoc/files.html).** ## Namespaces, classes, and methods The C programming language uses function prefixes and handles instead of namespaces and classes to model interfaces. All types in the Pdftools SDK, including handles and enumerations, are defined in the `PdfTools_Types.h` header file. Types have the following naming scheme: ``` T‹prefix›_‹type› ``` where `‹prefix›` is a shortened namespace prefix and `‹type›` is the name of the type. Similarly, the Pdftools SDK defines functions, collected in header files `Pdftools_‹sub-prefix›.h` with the following naming convention: ``` ‹prefix›_‹type›_‹name› ``` where `‹type›` is the class name and `‹name›` is the name of the function. ## Objects Objects in the Pdftools SDK for C package interface are represented by object handles. Some types are disposable, which means you must close them by calling `‹prefix›_‹type›_Close`. Release all other types by calling `‹prefix›_Release`. ### Type casting The Pdftools SDK uses a class hierarchy to model parent-child relationships, where a parent type `T‹prefix›_‹parentType›` can have derived child types `T‹prefix›_‹childType›`. Downcasting is necessary, for example, to call the functions of an object's parent class. In this case, you can cast a handle of the child type using a C-style cast: ``` (T‹prefix›_‹parentType›*)pChildTypeHandle ``` Upcasting is also possible using a C-style cast. Before casting, you can determine the child type using the `GetType` function of the parent class: ``` (T‹prefix›_‹parentType›Type) iChildType = ‹prefix›_‹parentType›_GetType(pParentTypeHandle); ``` ## Properties Properties are modeled with setter and getter functions `‹prefix›_‹type›_Get‹name›` and `‹prefix›_‹type›_Set‹name›`, where `‹name›` is the name of the property. ## Error handling After calling a function, detect any errors as follows: 1. If the return type of the function is `BOOL` or a pointer, and the return value is `FALSE` or `NULL` respectively, call the `PdfTools_GetLastError` function. If this method returns `ePdfTools_Error_Success`, then no error occurred and the return value is legitimate. 2. If the return type of the function isn't a Boolean or a pointer, call the `PdfTools_GetLastError` function. If this method returns `ePdfTools_Error_Success`, then no error occurred. To get more information about the error, use the `PdfToolsGetLastErrorMessage` function. ## Strings All functions involving strings are provided in two different flavors: - UTF-16 function with suffix `W` that uses `WCHAR` as the parameter type. - Multi-byte character set function with suffix `A` that uses `char` as the parameter type. The concrete character set that's used depends on the platform: - On Windows, the current ANSI code page (`CP_ACP`) is assumed. - On Linux or macOS, the current C encoding (`LC_CTYPE`) is used. In addition to the function names with suffix, there's a macro without suffix for each function pair. The macro resolves to one of the function variants: - `W` if `_UNICODE` is defined. - `A` if `_UNICODE` isn't defined. :::info[Example] Signature example of an API string property setter, where `‹name›` stands for the property’s name: ```c // Multibyte encoding: void ‹prefix›_‹type›_Set‹name›A(T‹prefix›_‹type›* pHandle, const char* szString); // UTF-16: void ‹prefix›_‹type›_Set‹name›W(T‹prefix›_‹type›* pHandle, const WCHAR* szString); #ifdef _UNICODE #define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›W #else #define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›A #endif ``` ### String return values In C, functions that return a string have a special behavior. Instead of returning the string, those functions take a buffer and a size as the last parameters and write into that buffer. The return value is the amount of data written to the buffer. To determine the required buffer size, call the function with `NULL` as the buffer argument. Calling a function with a buffer size that's too small results in an error. Multibyte character set functions (with the suffix `A`) that return a string may fail to correctly encode the string in the encoding of the current operating system. In this case, the return value is 0 and no error code is set. To prevent such failures, use the UTF-16 (`W`) functions on Windows or use operating systems with a Unicode code page. :::info[Example] Signature example usage of an API string property getter: ```c size_t PdfTools_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize); ``` ```c size_t nBufferSize = PdfTools_Sdk_GetVersionA(NULL, 0); char* pBuffer = malloc(nBufferSize * sizeof (char)); nBufferSize = PdfTools_Sdk_GetVersionA(pBuffer, nBufferSize); ``` ## Streams Streams use a set of callbacks and a context pointer, grouped in a struct `TPdfToolsSys_StreamDescriptor`. An implementation for `FILE*` is provided in the header file `PdfTools_PdfToolsSys.h`. Search for the `PdfToolsSysCreateFILEStreamDescriptor` function. ## Arrays In C, arrays work similarly to strings. Array parameters consist of a pointer to a buffer and a size parameter specifying the number of array elements. Functions that return an array take a buffer and a size as last parameters and write into that buffer. The return value is the number of elements written to the buffer. A return value of `(size_t)-1` indicates an error. To determine the required buffer size, call the function with `NULL` as the buffer argument. Calling the function with a buffer size that's too small results in an error. ## Lists Every list type `T‹prefix›_‹list›` provides a subset of the following functions, where `T‹prefix›_‹eltype›` stands for the type of the contained elements: | Function | Description | Possible errors | | ------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | | `int` `‹prefix›_‹list›_GetCount(T‹prefix›_‹list›*)` | Get the number of elements in the list. | `ePdfTools_Error_IllegalState` | | `T‹prefix›_‹eltype›*` `‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)` | Get an element of the list. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_UnsupportedOperation` | | `BOOL` `‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)` | Add an element to the end of the list. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_UnsupportedOperation` | ## Maps A map is a dictionary with unique keys and associated values. Currently, the only key type in all maps in the API is a string. Every map type `T‹pre›_‹map›` provides a subset of the following functions, where `T‹pre›_‹eltype›` is the type of the contained values. | Function | Description | Possible errors | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `int` `‹pre›_‹map›_GetSize(T‹pre›_‹map›*)` | The number of key-­value pairs in the map. | `ePdfTools_Error_IllegalState` | | `int` `‹pre›_‹map›_GetBegin(T‹pre›_‹map›*)` | Get the position of the first entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. Use `‹pre›_‹map›_GetNext` to get the position of the next entry. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetEnd(T‹pre›_‹map›*)` | Get the end position of the map. This position doesn't correspond to an actual entry in the map. It must be used to determine whether the end of the map has been reached when using `‹pre›_‹map›_GetBegin` and `‹pre›_‹map›_GetNext`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetNext(T‹pre›_‹map›*, int it)` | Get the position of the next entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetA(T‹pre›_‹map›*, const char* szKey)` | Get the position of a key in the map. If no error occurred, then the position can be used to get the corresponding value with `‹pre›_‹map›_GetValue`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_NotFound` | | `size_t` `‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)` | Get the key of the entry given a position. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)` | Get the value of the entry given a position. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_SetA(T‹pre›_‹map›*, const char* szKey, T‹pre›_‹eltype›* pValue)` | Set the value of an entry for a given key. This operation invalidates all positions previously returned by `‹pre›_‹map›_GetBegin`, `‹pre›_‹map›_GetEnd`, `‹pre›_‹map›_GetNext`, and `‹pre›_‹map›_Get`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_SetValue(T‹pre›_‹map›*, int it, T‹pre›_‹eltype›* pValue)` | Set the value of the entry at a position in the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_Clear(T‹pre›_‹map›*)` | Remove all entries from the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)` | Remove the entry at a position in the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | --- ## .NET technical notes Learn about specifics of the .NET interface of the Pdftools SDK. **tip: For the full API reference for the Pdftools SDK, see the [.NET API reference](https://pdf-tools.com/docs/pdf-tools-sdk/api-reference/latest/dotnet/html/R_Project_API_Reference.htm).** ## IDisposable objects Objects that must be closed explicitly (for example, `PdfTools.Pdf.Document`, `PdfTools.Image.Document`, `PdfTools.Crypto.Providers.Provider`, or subclasses) implement the `IDisposable` interface. Instead of calling `Dispose()` directly, use the `using` statement: ``` using (Document document = ...) { ... } // document.Dispose() is called implicitly here ``` ## Error handling Errors are reported using exceptions. Where applicable, the SDK maps errors to corresponding native exception classes, such as `System.ArgumentException`, `System.InvalidOperationException`, `System.NotSupportedException`, or `System.IO.IOException`. The remaining errors are modeled using exception classes that inherit from a base class `PdfToolsException`. ## Streams The native stream interface `System.IO.Stream` is used. ## Lists and iterables The API uses different concepts for returning collections of elements depending on the context: - Lists (`System.Collections.Generic.IList`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible. - Iterables (`System.Collections.Generic.IEnumerable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements. ## Maps Maps implement the native dictionary interface `System.Collections.Generic.IDictionary`. ## Namespace The Pdftools SDK uses the namespace `PdfTools`. **note: We recommend using a custom, company-specific namespace for your code.** Using the `PdfTools` namespace like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project. --- ## General technical notes This documentation explains how the Pdftools SDK interacts with your local operating system to [locate fonts](#locate-fonts), [locate color profiles](#locate-color-profiles), and store [temporary files](#temporary-files-directory) and [cache files](#cache-directory). ## Locate 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). ### 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\\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](http://corefonts.sourceforge.net/). For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq). **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](http://corefonts.sourceforge.net/). For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq). **The font directories for macOS are the following:** 1. `/System/Library/Fonts` 2. `/Library/Fonts` The SDK traverses the directories recursively in this order. ### Add custom font lookup paths In addition to the directories listed above, developers can specify custom font lookup paths using the following methods: * C: [PdfTools_Sdk_AddFontDirectoryA](https://api-reference.pdf-tools.com/pdfsdk/1.17/cdoc/_pdf_tools___pdf_tools_8h.html#afb5780e0a309889566e945040deffb74) or [PdfTools_Sdk_AddFontDirectoryW](https://api-reference.pdf-tools.com/pdfsdk/1.17/cdoc/_pdf_tools___pdf_tools_8h.html#a8b13e5d769c96c96edf4af36c57c6dbc) * C#: [Sdk.AddFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.17/dotnet/html/M_PdfTools_Sdk_AddFontDirectory.htm) * Java: [Sdk.addFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.17/javadoc/com/pdftools/Sdk.html#addFontDirectory(java.lang.String)) * Python: [sdk.add_font_directory](https://api-reference.pdf-tools.com/pdfsdk/1.17/pydocs/_autosummary/pdftools_sdk.sdk.html#pdftools_sdk.sdk.Sdk.add_font_directory) ### 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 `/Installed Fonts` of the cache directory. ## Locate 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: **Windows:** 1. `%SystemRoot%\System32\spool\drivers\color` 2. directory `Icc`, which must be a direct sub-directory of where the `PdfToolsSdkAPI.dll` resides. **Linux:** 1. `$PDF_ICC_PATH` if the environment variable is defined 2. the current working directory **macOS:** 1. `$PDF_ICC_PATH` if the environment variable is defined 2. the current working directory 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: - [Pdftools color profiles](http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip) - [ICC sRGB profiles](http://www.color.org/srgbprofiles.html) - [Adobe ICC Profiles](https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html) ## 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: **Windows:** 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. **Linux:** 1. The path specified by the `$PDFTMPDIR` environment variable. 2. The path specified by the `$TMP` environment variable. 3. The `/tmp` directory. **macOS:** 1. The path specified by the `$PDFTMPDIR` environment variable. 2. The path specified by the `$TMP` environment variable. 3. The `/tmp` 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. **Windows:** If the user has a profile: ``` %LOCAL_APPDATA%\PDF Tools AG\Caches ``` If the user has no profile: ``` \PDF Tools AG\Caches ``` **Linux:** If the user has a home directory: ``` ~/.pdf-tools/Caches ``` If the user has no home directory: ``` /pdf-tools/Caches ``` The `` refers to the [directory for temporary files](#temporary-files-directory). **macOS:** If the user has a home directory: ``` ~/.pdf-tools/Caches ``` If the user has no home directory: ``` /pdf-tools/Caches ``` The `` refers to the [directory for temporary files](#temporary-files-directory). --- ## Java technical notes Learn about technical details of the Pdftools SDK for Java. **tip: For the full API reference for the Pdftools SDK, see the [Java API reference](https://pdf-tools.com/docs/pdf-tools-sdk/api-reference/latest/javadoc/index.html?overview-summary.html).** ## AutoCloseable objects Objects that must be closed explicitly (for example, `com.pdftools.pdf.Document`, `com.pdftools.image.Document`, `com.pdftools.crypto.providers.Provider`, or subclasses) implement the `java.lang.AutoCloseable` interface. Instead of calling `close()` directly, use the "try-with-resources" statement: ``` try (Document document = ...) { ... } // document.close() is called implicitly here ``` ## Properties Properties are modeled with setter and getter methods. ## Error handling Errors are reported using exceptions. Where applicable, the SDK maps errors to corresponding native runtime exceptions, such as `java.lang.IllegalArgumentException`, `java.lang.IllegalStateException`, `java.lang.UnsupportedOperationException`, or `java.io.IOException`. The remaining errors are modeled using exception classes that inherit from a base class `PdfToolsException`. ## Streams The native stream interfaces can't be used because they're lacking two important features: - The PDF file format is based on random access. Native Java streams have only limited support for this. - The ability to read from an output stream is crucial for processing large files. Instead, a custom stream interface `com.pdftools.sys.Stream` is provided. A `FileStream` implementation for files is provided, backed by `java.io.RandomAccessFile`. For in-memory processing, a `MemoryStream` implementation is provided. ## Lists and iterables The API uses different concepts for returning collections of elements depending on the context: - Lists (`java.util.List`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible. - Iterables (`java.util.Iterable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements. ## Maps Maps implement the native Java map interface `java.util.Map`. ## Package The Pdftools SDK uses the package `com.pdftools`. **note: We recommend using a custom, company-specific package for your code.** Using the `com.pdftools` package like the SDK can lead to problems with ambiguous class names, especially when you use multiple Pdftools SDKs in the same project. --- ## Pdftools SDK code samples :::caution[Code samples temporarily unavailable] The code sample repositories for Pdftools SDK and Toolbox add-on are offline. We apologize for the inconvenience. If you need a code sample, [contact support](https://www.pdf-tools.com/docs/support/#open-a-support-request). Find Pdftools SDK code samples on GitHub and on Google Colab. Clone a GitHub repository to get the code, test Pdftools SDK features using sample PDFs included in each example, and check a per-sample README with instructions on how to run the sample. You can also open Jupyter notebooks in Google Colab to run code examples in your browser without a local setup. New to the SDK? Start with `Pdf2ImgSimple`, the entry-point sample used in the [getting-started guides](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/). :::note[Colab lists notebooks for two SDKs] The Colab dialog opens the shared `components-code-sample-hub` repository, which holds notebooks for both the Pdftools SDK and the Toolbox add-on SDKs. The dialog has no built-in filter. To find Pdftools SDK notebooks: 1. Open your browser's find-on-page bar with `Cmd`+`F` on macOS or `Ctrl`+`F` on Windows and Linux. 1. Enter the prefix `pdftools_sdk_`. 1. Click a matching notebook to open it in Colab. --- ## Getting started with the Pdftools SDK Get up and running with the Pdftools SDK and the Pdftools SDK Shell Tool. Find an integration guide in your language or framework: ## Trial license You can use the same license key for the Pdftools SDK, the Pdftools SDK Shell Tool, and the Toolbox add-on. The Pdftools SDK and the Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. --- ## Getting started with the Pdftools SDK(Pdftools-sdk) Welcome to the Pdftools SDK getting started guides. The Pdftools SDK is a comprehensive development library that lets developers integrate advanced PDF functionalities into in-house applications. Guides for C, .NET, Java, and Python explain how to work with a code example, and then walk you through the steps necessary to integrate the SDK into your application. The Pdftools SDK guide for other languages provides steps to use the Pdftools SDK with other programming languages. Go is used as an illustrative example. ## Trial license You can use the same license key for the Pdftools SDK, the Pdftools SDK Shell Tool, and the Toolbox add-on. The Pdftools SDK and the Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. --- ## Get started with C This guide walks you through the steps to use a code example, and then explains how to integrate the Pdftools SDK into your application with the C programming language. **tip: Try the Pdftools SDK without a license key.** ## Get started with a sample project Learn how to use the Pdftools SDK using a C code example. The Pdf2ImgSimple example converts a PDF file to an image. Use similar steps to run any other code example from the [sdk-examples-c](https://github.com/pdf-tools/sdk-examples-c) repository. ### Prerequisites This code example uses **GCC toolset 4.8+** and **CMake version 3.16** or higher. ### Compile and run the sample 1. Clone the **[sdk-examples-c](https://github.com/pdf-tools/sdk-examples-c)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-c.git ``` 1. Navigate to the `Pdf2ImgSimple` code example: ```bash cd sdk-examples-c/Pdf2ImgSimple ``` 1. Configure the project: ```shell cmake . ``` 1. Build the sample: ```shell cmake --build . ``` 1. The code example contains a PDF file `PdfPrimerWhitePaper.pdf`. To render it in multi-page TIFF image format, run: ```shell ./pdftoolspdf2imgsimple PdfPrimerWhitePaper.pdf PdfPrimerWhitePaper.tiff ``` The sample runs without a license key, and the output carries a watermark. To remove the watermark, open `pdftoolspdf2imgsimple.c` and uncomment the `PdfTools_Sdk_Initialize` function call in `main()`. Replace the `"insert-license-key-here"` placeholder with your license key. Include the less-than (`<`) and greater-than (`>`) signs. The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Compare the command syntax with a placeholder to the previous procedure: ```shell ./pdftoolspdf2imgsimple INPUT_FILE OUTPUT_FILE ``` **note: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page.** ## Integrate the SDK into your application Integrate and initialize the Pdftools SDK into your application. ### Add the SDK to your project 1. Click the **[download link](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_C-latest.zip)** to get the latest version of the Pdftools SDK for C in a zip archive. Optional: For older Linux distributions running glibc 2.12+, download the SDK from a [separate download](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_glibc2.12-latest.zip). 1. Unzip the file on your machine into a local directory recommended for your operating system. For example: **Windows:** ``` C:\Program Files\PDF Tools AG\ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `~` | Contains important information in the `README.md` file. | | `lib` | Runtime executable binaries and runtime import libraries: `win-x86\PdfToolsSdk.dll` and `win-x86\PdfToolsSdk.lib` for 32-bit Windows.`win-x64\PdfToolsSdk.dll` and `win-x64\PdfToolsSdk.lib` for 64-bit Windows.`win-arm64\PdfToolsSdk.dll` and `win-arm64\PdfToolsSdk.lib` for 64-bit Windows ARM. | | `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. | **Linux:** ``` /opt/pdftools.com/ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | `~` | Contains important information in the `README.md` file. | | `lib` | Runtime executable binaries for all supported platforms: `linux-x64/libPdfToolsSdk.so` for 64-bit Linux`linux-arm64/libPdfToolsSdk.so` for 64-bit Linux ARM | | `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. | **macOS:** ``` /opt/pdftools.com/ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `~` | Contains important information in the `README.md` file. | | `lib` | Runtime executable binaries: `osx-x64/libPdfToolsSdk.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfToolsSdk.dylib` for ARM (Apple Silicon) macOS | | `include` | Header files to add to your C or C++ project. The main header `PdfTools.h` includes all the other headers. | 1. Optional: The native libraries must be available in your compiler's library path. This step is only required if your build process doesn't resolve it automatically: **Windows:** Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable. **Linux:** Create a link to the shared library from one of the standard library directories, e.g: ``` ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfToolsSdk.so /usr/lib ``` **macOS:** Create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac): ``` ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfToolsSdk.dylib /usr/lib ``` ### Optional: Initialize the SDK Learn how to remove watermarked output of the Pdftools SDK using a valid license key. **tip: Initialization removes watermarks from output files and readies the SDK for production. Without a license key, output files carry a watermark.** :::info[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For more information, review [the Pdftools SDK license management](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/). To remove watermarks, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `PdfTools_Sdk_Initialize` once at application startup, before any other Pdftools SDK function call: ```c GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfTools_Sdk_Initialize(_T("YOUR_LICENSE_KEY"), NULL), _T("Failed to set the license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `PdfTools_Sdk_Initialize` function, follow these steps: 1. Clone the **[sdk-examples-c](https://github.com/pdf-tools/sdk-examples-c)** repository and navigate to a sample directory. For example, `sdk-examples-c/Pdf2ImgSimple`. 1. Open the main C file and find the commented-out `PdfTools_Sdk_Initialize` call. For example, the [Pdf2ImgSimple C sample](https://github.com/pdf-tools/sdk-examples-c/tree/main/Pdf2ImgSimple) includes it in `pdftoolspdf2imgsimple.c`. 1. Uncomment the call and replace the `"insert-license-key-here"` placeholder with your license key. ### Uninitialize the SDK After processing files with the Pdftools SDK, call `PdfTools_Uninitialize` to unload the library correctly: ```c // Uninitialize library PdfTools_Uninitialize(); ``` ### Implement your use case - Find more use cases and code examples on the [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page. - For more technical information about the Pdftools SDK for C, consult the [C technical notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/c-notes). - If you need to configure a proxy, review [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section. --- ## Get started with .NET This guide walks you through the steps to use a code example, and then explains how to integrate the Pdftools SDK into your application with .NET. **tip: Try the Pdftools SDK without a license key.** ## Prerequisites The Pdftools SDK for .NET requires **.NET and .NET Core 2.0 or higher**, or **.NET Framework 4.6.1 or higher**. ## Get started with a sample project Learn how to use the Pdftools SDK using a C# code example. The Pdf2ImgSimple example converts a PDF file to an image. Use similar steps to run any other code example from the [sdk-examples-csharp](https://github.com/pdf-tools/sdk-examples-csharp) repository. ### Compile and run the sample Switch between the tabs to display steps for the command line interface or Visual Studio. To compile and run the sample, follow these steps: **Command line:** 1. Clone the **[sdk-examples-csharp](https://github.com/pdf-tools/sdk-examples-csharp)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-csharp.git ``` 1. Navigate to the `Pdf2ImgSimple` code example: ```bash cd sdk-examples-csharp/Pdf2ImgSimple ``` 1. To render the sample PDF file `PdfPrimerWhitePaper.pdf` to a multi-page TIFF image format, run: ```shell dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj PdfPrimerWhitepaper.pdf tiff_output.tiff ``` The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Compare the command syntax with a placeholder to the previous procedure: ```shell dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj INPUT_FILE OUTPUT_FILE ``` **Visual Studio:** **info: This documentation uses Visual Studio 2022.** 1. Clone the **[sdk-examples-csharp](https://github.com/pdf-tools/sdk-examples-csharp)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-csharp.git ``` 1. Open the project in Visual Studio: ``` sdk-examples-csharp/Pdf2ImgSimple/PdfToolsPdf2ImgSimple.csproj ``` 1. Click **Build** -> **Build Solution** to compile the project. 1. Within the code example, open your terminal. 1. The code example contains a PDF file `PdfPrimerWhitePaper.pdf`. To render it in multi-page TIFF image format, run: ``` ./bin/Debug/net6.0/PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff ``` The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Compare the command syntax with a placeholder to the previous procedure: ```shell ./bin/Debug/net6.0/PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE ``` The sample runs without a license key, and the output carries a watermark. To remove the watermark, open `Program.cs` and uncomment the `Sdk.Initialize` method call in `Main()`. Replace the `"insert-license-key-here"` placeholder with your license key. Include the less-than (`<`) and greater-than (`>`) signs. **tip: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page.** ## Integrate the SDK into your application Integrate and initialize the Pdftools SDK into your application. ### Add the SDK to your project **Command line:** In the project directory, add the Pdftools SDK NuGet package: ```shell dotnet add package PdfTools ``` Optional: To install a specific version of the Pdftools SDK, run: ```shell dotnet add package PdfTools --version VERSION_NUMBER ``` Replace the `VERSION_NUMBER` with a specific version of the Pdftools SDK you want to add to your project. **Visual Studio:** **info: This documentation uses Visual Studio 2022 on Windows. ** 1. Open your solution in Visual Studio. 1. Click **Tools** > **Nuget Package Manager** > **Manage NuGet Packages for Solution...**. 1. Click the **Search** tab and search for `Pdftools SDK`. 1. Select the NuGet package named `PdfTools by PDF Tools AG`, select your Project, and then click **Install**. 1. Click **OK** to allow the changes, and then review and **Accept** the license agreement. ### Optional: Initialize the SDK Learn how to remove watermarked output of the Pdftools SDK using a valid license key. **tip: Initialization removes watermarks from output files and readies the SDK for production. Without a license key, output files carry a watermark.** :::info[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For more information, review [the Pdftools SDK license management](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/). To remove watermarks, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.Initialize` once at application startup, before any other Pdftools SDK method call: ```csharp Sdk.Initialize("YOUR_LICENSE_KEY"); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.Initialize` method, follow these steps: 1. Clone the **[sdk-examples-csharp](https://github.com/pdf-tools/sdk-examples-csharp)** repository and navigate to a sample directory. For example, `sdk-examples-csharp/Pdf2ImgSimple`. 1. Open `Program.cs` and find the commented-out `Sdk.Initialize` call. For example, the [Pdf2ImgSimple C# sample](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Pdf2ImgSimple) includes it in `Program.cs`. 1. Uncomment the call and replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case - Find more use cases and code examples on the [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page. - For more technical information about the Pdftools SDK for .NET, consult the [.NET technical notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/dotnet-notes). - If you need to configure a proxy, review [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section. --- ## Get started with Java This guide walks you through the steps to use a code example, and then explains how to integrate the Pdftools SDK into your application with the Java programming language. **tip: Try the Pdftools SDK without a license key.** ## Prerequisites The Pdftools SDK for Java requires **Java version 8 or higher**. ## Get started with a sample project Learn how to use the Pdftools SDK using a Java code example. The Pdf2ImgSimple example converts a PDF file to an image. Use similar steps to run any other code example from the [sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java) repository. ### Compile and run the sample Switch between the following tabs to display steps for the CLI (Maven or Gradle), Eclipse IDE, or IntelliJ IDEA. To compile and run the sample, follow these steps: **CLI: Maven:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Navigate to the `Pdf2ImgSimple` code example: ```bash cd sdk-examples-java/Pdf2ImgSimple ``` 1. Build and run the sample: ```bash mvn clean install mvn exec:java -Dexec.mainClass="PdfToolsPdf2ImgSimple.PdfToolsPdf2ImgSimple" -Dexec.args="PdfPrimerWhitepaper.pdf tiff_output.tiff" ``` The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Compare the command syntax with a placeholder to the previous procedure: ```bash mvn exec:java -Dexec.mainClass="PdfToolsPdf2ImgSimple.PdfToolsPdf2ImgSimple" -Dexec.args="INPUT_FILE OUTPUT_FILE" ``` **CLI: Gradle:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Navigate to the `Pdf2ImgSimple` code example: ```bash cd sdk-examples-java/Pdf2ImgSimple ``` 1. Build and run the sample: ```bash ./gradlew run --args="PdfPrimerWhitepaper.pdf tiff_output.tiff" ``` :::note - On Windows, use `gradlew` (or `gradlew.bat`) instead of `./gradlew`. - On macOS and Linux, you may need to make the wrapper executable first: `chmod +x gradlew` ::: The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Review the following snippet with a placeholder and compare it to the last step of the previous procedure: ```bash ./gradlew run --args="INPUT_FILE OUTPUT_FILE" ``` **Eclipse IDE:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Open Eclipse and navigate to **File** > **Import**. 1. Select **Maven** > **Existing Maven Projects** (or **Gradle** > **Existing Gradle Project**) and click **Next**. 1. Browse to `sdk-examples-java/Pdf2ImgSimple` and click **Finish**. 1. In the **Package Explorer**, locate the main class containing the `main` method. 1. Right-click the file and select **Run As** > **Java Application**. **IntelliJ IDEA:** 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-java.git ``` 1. Open IntelliJ IDEA and navigate to **File** > **Open**. 1. Select `sdk-examples-java/Pdf2ImgSimple` and click **OK**. 1. When prompted, choose to import the project as a **Maven** or **Gradle** project. 1. In the **Project** tool window, locate the main class containing the `main` method. 1. Right-click the file and select **Run 'PdfToolsPdf2ImgSimple'**. The sample runs without a license key, and the output carries a watermark. To remove the watermark, open the main Java file (for example, `lib/src/main/java/PdfToolsPdf2ImgSimple/PdfToolsPdf2ImgSimple.java`) and uncomment the `Sdk.initialize` method call in `main()`. Replace the `"insert-license-key-here"` placeholder with your license key. Include the less-than (`<`) and greater-than (`>`) signs. **note: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page.** ## Integrate the SDK into your application Integrate and initialize the Pdftools SDK into your application. ### Add the SDK to your project To add the Pdftools SDK to your project, use one of the following methods: **Maven:** The Pdftools SDK for Java is available on Maven Central. To add the Pdftools SDK for Java to your project, add the following to your `pom.xml`: ```xml com.pdftools pdftools-sdk 1.17.0 ``` The dependency includes native binaries for all supported platforms, which are loaded automatically at runtime. **Gradle:** The Pdftools SDK for Java is available on Maven Central. To add the Pdftools SDK for Java to your project, add the following to your `build.gradle`: ```groovy implementation 'com.pdftools:pdftools-sdk:1.17.0' ``` The dependency includes native binaries for all supported platforms, which are loaded automatically at runtime. **Manual:** 1. Download [`pdftools-sdk-1.17.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.17.0/pdftools-sdk-1.17.0.jar) from Maven Central ([sources jar](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.17.0/pdftools-sdk-1.17.0-sources.jar), [javadoc jar](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.17.0/pdftools-sdk-1.17.0-javadoc.jar)). 1. Download [`pdftools-sdk-native-1.17.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk-native/1.17.0/pdftools-sdk-native-1.17.0.jar) from Maven Central (native libraries). 1. Add both JARs to your project's classpath. ### Optional: Initialize the SDK Learn how to remove watermarked output of the Pdftools SDK using a valid license key. **tip: Initialization removes watermarks from output files and readies the SDK for production. Without a license key, output files carry a watermark.** :::info[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For more information, review [the Pdftools SDK license management](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/). To remove watermarks, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.initialize` once at application startup, before any other Pdftools SDK method call: ```java Sdk.initialize("YOUR_LICENSE_KEY"); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.initialize` method, follow these steps: 1. Clone the **[sdk-examples-java](https://github.com/pdf-tools/sdk-examples-java)** repository and navigate to a sample directory. For example, `sdk-examples-java/Pdf2ImgSimple`. 1. Open the main Java file and find the commented-out `Sdk.initialize` call. For example, the [Pdf2ImgSimple Java sample](https://github.com/pdf-tools/sdk-examples-java/tree/main/Pdf2ImgSimple) includes it in `lib/src/main/java/PdfToolsPdf2ImgSimple/PdfToolsPdf2ImgSimple.java`. 1. Uncomment the call and replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case - Find more use cases and code examples on the [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page. - For more technical information about the Pdftools SDK for Java, consult the [Java technical notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/java-notes). - If you need to configure a proxy, review [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section. --- ## Get started with other programming languages Use the Pdftools SDK with Go, Rust, and potentially many other programming languages by binding the C API. The Pdftools SDK includes a powerful C API for high-performance applications, which can be used with a wide range of programming languages not directly supported by the Pdftools SDK. This guide illustrates the binding of the C API on a Go example. **Pdftools customers use interface bindings to implement the Pdftools SDK with the following programming languages and frameworks:** - Delphi - Go - Lua - Node.js - Perl - PHP - R - Ruby - Rust **note: Pdftools do not officially support and cannot guarantee the stability of such interface bindings. This approach requires you to be very familiar with your chosen language and how it integrates with C.** ## Prerequisites Install [Go 1.6](https://go.dev/dl/) or higher on your system, and include the Go executable files in your path. ## Use the Pdftools SDK with Go Go provides a standard library package [cgo](https://pkg.go.dev/cmd/cgo) which makes it easy to bind the Pdftools SDK's C API. Learn how to use the Go programming language to convert a PDF document to an image in this example. **note: These instructions explain the process by which you create a Go wrapper for the Pdftools SDK. For simplicity, some functionality such as error handling is not shown in the example code.** 1. Create a project directory named `pdf2img`. 2. Extract the latest `Pdftools SDK for C` zip file into the `pdf2img` directory, then rename the extracted directory to `PdftoolsSDK`. The project structure looks like the following: ``` pdf2img └── PdftoolsSDK ├── include └── lib ``` 3. Create a new file in the top-level project directory and name it `pdf2img.go`, and then add this code: **Windows:** ```go package main // #cgo CFLAGS: -IPdftoolsSDK/include // #cgo LDFLAGS: -LPdftoolsSDK/lib/win-x64 -Wl,-rpath,PdftoolsSDK/lib/win-x64 -lPdfToolsSdk // #include "PdfTools_Platform.h" // #include "PdfTools_PdfTools.h" // #include "PdfTools_PdfToolsSys.h" // #include "PdfTools_PdfToolsPdf.h" // #include "PdfTools_PdfToolsImage.h" // #include "PdfTools_PdfToolsPdf2Image.h" // #include "PdfTools_PdfToolsPdf2ImageProfiles.h" // #include // #include import "C" import ( "os" "unsafe" ) func main() { // Initialize the SDK C.PdfTools_Initialize() demokey := C.CString("") C.PdfTools_Sdk_Initialize(demokey, nil) szInPath := C.CString(os.Args[1]) szInParms := C.CString("rb") szOutPath := C.CString(os.Args[2]) szOutParms := C.CString("wb+") // Open input document pInStream := C.fopen(szInPath, szInParms) var inDesc *C.TPdfToolsSys_StreamDescriptor inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0) pInDoc := C.PdfToolsPdf_Document_Open(inDesc, C.CString("")) // Create output stream for writing pOutStream := C.fopen(szOutPath, szOutParms) var outDesc *C.TPdfToolsSys_StreamDescriptor outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0) // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. pProfile := (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New()) // Convert the PDF document to an image document pConverter := C.PdfToolsPdf2Image_Converter_New() pOutDoc := (*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile)) // Clean up resources if pOutDoc != nil { C.PdfToolsImage_Document_Close(pOutDoc) } C.PdfTools_Release(unsafe.Pointer(pConverter)) C.PdfTools_Release(unsafe.Pointer(pProfile)) if pOutStream != nil { C.fclose(pOutStream) } if pInDoc != nil { C.PdfToolsPdf_Document_Close(pInDoc) } if pInStream != nil { C.fclose(pInStream) } C.free(unsafe.Pointer(szInPath)) C.free(unsafe.Pointer(szInParms)) C.free(unsafe.Pointer(szOutPath)) C.free(unsafe.Pointer(szOutParms)) C.PdfTools_Uninitialize() } ``` **Linux:** ```go package main // #cgo CFLAGS: -IPdftoolsSDK/include // #cgo LDFLAGS: -LPdftoolsSDK/lib/linux-x64 -Wl,-rpath,PdftoolsSDK/lib/linux-x64 -lPdfToolsSdk // #include "PdfTools_Platform.h" // #include "PdfTools_PdfTools.h" // #include "PdfTools_PdfToolsSys.h" // #include "PdfTools_PdfToolsPdf.h" // #include "PdfTools_PdfToolsImage.h" // #include "PdfTools_PdfToolsPdf2Image.h" // #include "PdfTools_PdfToolsPdf2ImageProfiles.h" // #include // #include import "C" import ( "os" "unsafe" ) func main() { // Initialize the SDK C.PdfTools_Initialize() demokey := C.CString("") C.PdfTools_Sdk_Initialize(demokey, nil) szInPath := C.CString(os.Args[1]) szInParms := C.CString("rb") szOutPath := C.CString(os.Args[2]) szOutParms := C.CString("wb+") // Open input document pInStream := C.fopen(szInPath, szInParms) var inDesc *C.TPdfToolsSys_StreamDescriptor inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0) pInDoc := C.PdfToolsPdf_Document_Open(inDesc, C.CString("")) // Create output stream for writing pOutStream := C.fopen(szOutPath, szOutParms) var outDesc *C.TPdfToolsSys_StreamDescriptor outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0) // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. pProfile := (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New()) // Convert the PDF document to an image document pConverter := C.PdfToolsPdf2Image_Converter_New() pOutDoc := (*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile)) // Clean up resources if pOutDoc != nil { C.PdfToolsImage_Document_Close(pOutDoc) } C.PdfTools_Release(unsafe.Pointer(pConverter)) C.PdfTools_Release(unsafe.Pointer(pProfile)) if pOutStream != nil { C.fclose(pOutStream) } if pInDoc != nil { C.PdfToolsPdf_Document_Close(pInDoc) } if pInStream != nil { C.fclose(pInStream) } C.free(unsafe.Pointer(szInPath)) C.free(unsafe.Pointer(szInParms)) C.free(unsafe.Pointer(szOutPath)) C.free(unsafe.Pointer(szOutParms)) C.PdfTools_Uninitialize() } ``` **macOS:** ```go package main // #cgo CFLAGS: -IPdftoolsSDK/include // #cgo LDFLAGS: -LPdftoolsSDK/lib/osx-arm64 -Wl,-rpath,PdftoolsSDK/lib/osx-arm64 -lPdfToolsSdk // #include "PdfTools_Platform.h" // #include "PdfTools_PdfTools.h" // #include "PdfTools_PdfToolsSys.h" // #include "PdfTools_PdfToolsPdf.h" // #include "PdfTools_PdfToolsImage.h" // #include "PdfTools_PdfToolsPdf2Image.h" // #include "PdfTools_PdfToolsPdf2ImageProfiles.h" // #include // #include import "C" import ( "os" "unsafe" ) func main() { // Initialize the SDK C.PdfTools_Initialize() // If you have a license key for the Pdftools SDK, add it here and un-comment these lines. // demokey := C.CString("") // C.PdfTools_Sdk_Initialize(demokey, nil) szInPath := C.CString(os.Args[1]) szInParms := C.CString("rb") szOutPath := C.CString(os.Args[2]) szOutParms := C.CString("wb+") // Open input document pInStream := C.fopen(szInPath, szInParms) var inDesc *C.TPdfToolsSys_StreamDescriptor inDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*inDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(inDesc, pInStream, 0) pInDoc := C.PdfToolsPdf_Document_Open(inDesc, C.CString("")) // Create output stream for writing pOutStream := C.fopen(szOutPath, szOutParms) var outDesc *C.TPdfToolsSys_StreamDescriptor outDesc = (*C.TPdfToolsSys_StreamDescriptor)(C.malloc(C.size_t(unsafe.Sizeof(*outDesc)))) C.PdfToolsSysCreateFILEStreamDescriptor(outDesc, pOutStream, 0) // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. pProfile := (*C.TPdfToolsPdf2ImageProfiles_Profile)(C.PdfToolsPdf2ImageProfiles_Archive_New()) // Convert the PDF document to an image document pConverter := C.PdfToolsPdf2Image_Converter_New() pOutDoc := (*C.TPdfToolsImage_Document)(C.PdfToolsPdf2Image_Converter_ConvertDocument(pConverter, pInDoc, outDesc, pProfile)) // Clean up resources if pOutDoc != nil { C.PdfToolsImage_Document_Close(pOutDoc) } C.PdfTools_Release(unsafe.Pointer(pConverter)) C.PdfTools_Release(unsafe.Pointer(pProfile)) if pOutStream != nil { C.fclose(pOutStream) } if pInDoc != nil { C.PdfToolsPdf_Document_Close(pInDoc) } if pInStream != nil { C.fclose(pInStream) } C.free(unsafe.Pointer(szInPath)) C.free(unsafe.Pointer(szInParms)) C.free(unsafe.Pointer(szOutPath)) C.free(unsafe.Pointer(szOutParms)) C.PdfTools_Uninitialize() } ``` :::tip The output file is watermarked by default. If you have a valid license key, replace `` with your Pdftools SDK license key. ::: 4. Open a terminal in the top-level project directory (`~/pdf2img`) and run: ``` go build ``` 5. An executable file named `pdf2img` is created in the top-level project directory. Test the executable by running the command: ``` pdf2img ``` For example, place a PDF file named `in.pdf` in the top-level project directory and run: ``` pdf2img in.pdf out.tif ``` An output image file named `out.tif` is created in the top-level project directory. ## Bind the C library and header files Bind the Pdftools SDK's C API to a different programming language using the native C library and header files. Click the **[download](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_C-latest.zip)** link to get the `Pdftools SDK for C` package. The method for using the native C library and header files differs slightly for each language. **tip: Without a valid license key, the output files carry a watermark. Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.** --- ## Get started with Python This guide walks you through the steps to use the Pdftools SDK in a code example with Python. The Python interface wraps the Pdftools SDK [C API](https://api-reference.pdf-tools.com/pdfsdk/latest/cdoc/files.html). **tip: Try the Pdftools SDK without a license key.** ## Prerequisites The Pdftools SDK for Python requires **Python 3.6 or higher**. ## Get started with a sample project Learn how to use the Pdftools SDK using a Python code example. The Pdf2ImgSimple example converts a PDF file to an image. Use similar steps to run any other code example from the [sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python) repository. ### Clone and run the sample 1. Clone the **[sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python)** repository: ```bash git clone https://github.com/pdf-tools/sdk-examples-python.git ``` 1. Navigate to the `Pdf2ImgSimple` code example: ```bash cd sdk-examples-python/Pdf2ImgSimple ``` 1. Install the Pdftools SDK package: ```bash pip install pdftools_sdk ``` 1. To render the sample PDF file `PdfPrimerWhitePaper.pdf` to a multi-page TIFF image format, run: ```shell python ./pdf2_img_simple.py PdfPrimerWhitePaper.pdf PdfPrimerWhitePaper.tiff ``` **note: Run `python3` instead on systems where only Python 3 is installed and `python` is not aliased.** The code example takes: - The input and output files are represented as a file name or a file path with the file name. - Both file paths (input and output) can be relative or absolute. Compare the command syntax with a placeholder to the previous procedure: ```bash python ./pdf2_img_simple.py INPUT_PDF IMAGE_OUTPUT_PATH ``` The sample runs without a license key, and the output carries a watermark. To remove the watermark, open `pdf2_img_simple.py` and uncomment the `Sdk.initialize` method call in the `if __name__ == "__main__":` block. Replace the `"insert-license-key-here"` placeholder with your license key. Include the less-than (`<`) and greater-than (`>`) signs. ## Integrate the SDK into your application Integrate and initialize the Pdftools SDK into your application. ### Add the SDK to your project 1. Install the Python package: ```shell pip install pdftools_sdk ``` 1. Clone the **[sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python)** repository and navigate to any sample directory. 1. Review the `README.md` file with usage details. Every code example includes a `README.md` with different usage instructions. 1. Import the required packages in the header of your Python code: ```python from ctypes import * from pdftools_sdk.pdf import Document from pdftools_sdk.pdf2_image import Converter from pdftools_sdk.pdf2_image.profiles import Archive ``` :::info[Imports depend on the sample you use] The imports depend on the Python sample you use. Imports displayed in the last step of the previous procedure are valid for the [Convert PDF to image](https://github.com/pdf-tools/sdk-examples-python/tree/main/Pdf2ImgSimple) sample. Every sample includes a single Python file from which you can copy the imports. To use a different feature, copy the correct imports into your project: 1. In the **[sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python)** repository, navigate to a sample directory. For example: `sdk-examples-python/Decrypt`. 1. Open the `decrypt.py` file, and then copy its imports to the header of your Python code. ### Optional: Initialize the SDK Learn how to remove watermarked output of the Pdftools SDK using a valid license key. **tip: Initialization removes watermarks from output files and readies the SDK for production. Without a license key, output files carry a watermark.** :::info[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. For more information, review [the Pdftools SDK license management](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/). To remove watermarks, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.initialize` once at application startup, before any other Pdftools SDK method call: ```python Sdk.initialize("YOUR_LICENSE_KEY") ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.initialize` method, follow these steps: 1. Clone the **[sdk-examples-python](https://github.com/pdf-tools/sdk-examples-python)** repository and navigate to a sample directory. For example, `sdk-examples-python/Pdf2ImgSimple`. 1. Open the main Python file and find the commented-out `Sdk.initialize` call. For example, the [Pdf2ImgSimple Python sample](https://github.com/pdf-tools/sdk-examples-python/tree/main/Pdf2ImgSimple) includes it in `pdf2_img_simple.py`. 1. Uncomment the call and replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case - Find more use cases and code examples on the [Code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) page. - If you need to configure a proxy, review [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section. --- ## Pdftools SDK Shell Tool Learn how to use the Pdftools SDK from the command line with the Pdftools SDK Shell Tool. ## Prerequisites The Pdftools SDK Shell Tool is available as: - Self-contained .NET distribution. - Framework-dependent .NET distribution. Use the self-contained distribution if you do not have the .NET framework installed. The framework-dependent distribution of the Pdftools SDK Shell Tool requires you to install [**.NET 6.0**](https://dotnet.microsoft.com/en-us/download) or higher. ## Download Download the latest version of the Pdftools SDK Shell Tool for the following platforms: | Platform | Self-contained distribution | Framework-dependent distribution | |------------|-----------------------------|----------------------------------| | linux-x64 | [PdfToolsSDK_Shell-latest-linux-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-linux-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-x64.zip) | | linux-arm64| [PdfToolsSDK_Shell-latest-linux-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-linux-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-linux-arm64.zip) | | osx-x64 | [PdfToolsSDK_Shell-latest-osx-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-osx-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-x64.zip) | | osx-arm64 | [PdfToolsSDK_Shell-latest-osx-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-osx-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-osx-arm64.zip) | | win-x64 | [PdfToolsSDK_Shell-latest-win-x64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-x64-self-contained.zip) | [PdfToolsSDK_Shell-latest-win-x64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-x64.zip) | | win-arm64 | [PdfToolsSDK_Shell-latest-win-arm64-self-contained.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-arm64-self-contained.zip) | [PdfToolsSDK_Shell-latest-win-arm64.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSHELL/latest/PdfToolsSDK_Shell-latest-win-arm64.zip) | :::tip[Older Linux systems] Separate binary files are available that support older Linux distributions using glibc2.12+. You can download these binary files from [PdfToolsSDK_glibc2.12-latest.zip](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_glibc2.12-latest.zip). ## Features The Pdftools SDK Shell Tool supports the following features: | Feature | Description | Version | |------------------------------|---------------------------------------------------------------------------------------------|---------| | Image to PDF | Convert images to PDF or PDF/A, with fit-to-page option | 1.0.0+ | | PDF to PDF/A | Validate PDF conformance; Convert to PDF/A; Embed associated files; Create ZUGFeRD invoices | 1.2.0+ | | Compression and optimization | Optimize for web, archive, print, or minimal file size; MRC optimization | 1.0.0+ | | Security | Sign, certify, and timestamp PDF documents; Validate digital signatures | 1.4.0+ | | Rendering | Render PDF pages to images for fax, archive, or viewing | 1.1.0+ | | Merging and splitting | Merge and split PDF documents; rotate pages during new PDF assembly | 1.1.0+ | | Text extraction | Extract text for LLM ingestion or layout-preserving output | 1.8.0+ | | OCR | Make scanned PDFs searchable, fix non-extractable text, and add accessibility tagging | 1.12.0+ | ## Usage The general usage is ```bash > pdf [sdk_options] [input_options] [: ] [ [output_options]] ``` ### Chain commands **tip: You can chain multiple commands using `:`. This way you can apply multiple operations without the need to store each result to an intermediate file.** Example: ```bash > pdf input.jpg import : optimize-web out.pdf ``` ### Detailed help For the full reference of commands and features of the Pdftools SDK Shell Tool use the built-in help by executing: ```bash # For all commands and features pdf help # For specific commands pdf help ``` ### Use of license key To use a license key and remove the watermarked results, insert the license key using the `-lk` parameter: ```shell > pdf -lk "" ``` Substitute: - `` with the value of your license key. - `` with a path to the input file. - `` with a specific command. - `` with a path to the output file. For example: ```shell > pdf -lk "" input.jpg import : optimize-web out.pdf ``` --- ## Guides # Pdftools SDK guides Learn about various functionalities of the Pdftools SDK. --- ## Archive with the Pdftools SDK With the Pdftools SDK you can archive files to the following formats: - [Archive a PDF document to PDF/A](#archive-pdf-to-pdfa) - [Archive images to accessible PDF/A](#archive-images-to-accessible-pdfa) - [Archive PDF to TIFF image archive](#archive-pdf-to-tiff-image-archive) --- ## Archive PDF to PDF/A With the Pdftools SDK, you can convert PDF documents to [PDF/A specification](https://www.pdf-tools.com/docs/knowledge/pdf-a/) (PDF/A-1, PDF/A-2, PDF/A-3), including all conformance levels (B, A, and U). You can read encrypted documents, repair or recover corrupt data and objects. You can remove content and convert embedded and attached files. :::note[Accepted formats] | Input format | Output format | |---|---| | PDF 1.x, PDF 2.0 | PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2a, PDF/A-2u, PDF/A-3b, PDF/A-3a, PDF/A-3u | **Input document processing** - Automatically determine optimal conformance based on input file (optional) - Recover corrupt documents - Repair corrupt data such as embedded font programs or images - Repair metadata and make them consistent **Color management and fonts** - Make color spaces device-­independent, for example, by embedding an ICC profile or setting an output intent - Manage colorants (PDF/A-2 and later) - Embed and subset fonts **Conversion process** - Control the conversion process with pre- and post-­validation, conversion reports, and application log files - Remove transparency (PDF/A-1 only) - Remove malicious content such as attached files (PDF/A-1 and PDF/A-2) and JavaScript actions - Remove multimedia content such as video and sound - Convert embedded and attached files (PDF/A-2 and later) :::tip[Get started] Learn how to **[archive a PDF file to a PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa)**. --- ## Archive images to accessible PDF/A Convert one or more single-page or multi-page raster images to an output PDF document with searchable text. :::note[Accepted formats] | Input | Output | | -------------------------------------------- | ---------------------------- | | TIFF, JPEG, BMP, GIF, PNG, JBIG2 or JPEG2000 | PDF/A-1a, PDF/A-2a, PDF/A-3a | **Image processing** - Select image compression, depending on the image type - Select image quality for lossy compression - Set standard resolution (DPI / X and Y coordinates) - Choose optional JPEG image recompression **Page layout** - Select PDF page size or determine automatically - Select page area - Set scaling - Set image position - Set image orientation (portrait or landscape) **PDF document settings** - Set encryption and user access permissions - Set document attributes - Select and embed ICC color profiles - Define alternative text (tagging) and image language - Embed XMP metadata :::tip[Get started] Learn how to **[archive an image to an accessible PDF/A document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-image-pdfa-accessible)**. ## Archive PDF to TIFF image archive Convert PDFs to TIFF images in a format suitable for archiving using the [Archive conversion profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#archive). :::note[Accepted formats] | Input | Output | | ------------------------------------------- | --------------- | | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | TIFF | **Image processing** - Set resolution (DPI) - Set TIFF file compression algorithm - Set the quality of lossy image compression **Color management** - Set background color - Set color space **Page layout** - Define page dimensions in standard page sizes, points or pixels - Set rotation: force portrait or landscape or inherit rotation from original document :::tip[Get started] Learn how to **[Archive PDF document to TIFF image archive](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-tiff)**. ## Archive conversion profile Conversion profiles define how an input file is converted and rendered in an output file. A profile contains a set of conversion parameters that are combined for a practical use case. For more information, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles) documentation. --- ## Archive an image to an accessible PDF Valid PDF/A documents with A-level (Accessibility) conformance (PDF/A-1a, PDF/A-2a, PDF/A-3a) must have text that can be reliably searched and copied. The content structure in the accessible PDF/A document can be accessed by technologies such as screen readers. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Img2PdfAccessibility)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Img2PdfAccessibility)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Img2PdfAccessibility)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Img2PdfAccessibility)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Img2PdfAccessibility)**. When archiving an image to a PDF/A document with A-level conformance, descriptive text must be provided for each page that is added to the document. For example, "This color image shows a small sailing boat at sunset". The language of the text must also be provided in ISO 3166:2013 format. For example, "en" or "de-CH". For scanned text documents, the [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) can be used to recognize the characters in the documents (OCR) and tag the image with the recognized structure and text. **info: For more background about converting images to PDF documents, see [Convert an image to a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/convert-image-pdf).** **Steps to archive a document** 1. [Read the input image](#read-the-input-image) 2. [Select a conversion profile](#select-a-conversion-profile) 3. [Specify the conformance level](#specify-the-conformance-level) 4. [Add accessible content](#add-accessible-content) 5. [Convert the image to a PDF document](#convert-the-image-to-a-pdf-document) 6. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input image First you need to read the image you want to convert. To do this, load the input image from the file system into a read-only image `Document`. This `Document` can then later be passed to the `Converter`. **.NET:** ```csharp // Open image document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr); ``` ## Select a conversion profile You start the image conversion process by creating a conversion `Profile` object. The `Profile` object defines the parameters that are applied to the conversion process. This example uses the `Archive` profile, which is intended for document workflows that convert images to PDF/A documents for archiving. **.NET:** ```csharp // Create the profile that defines the conversion parameters. // The Archive profile converts images to PDF/A documents for archiving. var profile = new Profiles.Archive(); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts images to PDF/A documents for archiving. Archive profile = new Archive(); ``` ## Specify the conformance level By default, the `Archive` profile produces output PDF documents with PDF/A-2b conformance. If the document workflow requires accessible content to be included in the output PDF, then conformance Level A (Accessible) should be used instead. This example sets the document conformance to PDF/A-2a. **.NET:** ```csharp // Set conformance of output document to PDF/A-2a profile.Conformance = new Conformance(2, Conformance.PdfALevel.A); ``` **Java:** ```java // Set conformance of output document to PDF/A-2a profile.setConformance(new Conformance(new Conformance.PdfAVersion(2, Level.A))); ``` ## Add accessible content For each page created in the output PDF/A document, alternate text must be added that represents the contents of the image on that page. In addition, the language of the text should be specified at a document level. **.NET:** ```csharp // For PDF/A level 2a, an alternate text is required for each page of the image. // This is optional for other PDF/A levels, e.g. PDF/A-2b. profile.Language = "en"; profile.AlternateText.Add(alternateText); ``` **Java:** ```java // For PDF/A level A, an alternate text is required for each page of the image. // This is optional for other PDF/A levels, e.g. PDF/A-2b. profile.setLanguage("en"); profile.getAlternateText().add(alternateText); ``` ## Convert the image to a PDF document After setting the appropriate `Profile` and `Conformance` levels, and adding accessible content, the final step is to instantiate a `Converter` object and call its `Convert` method. The output PDF/A document is created at the specified path. **.NET:** ```csharp // Create output stream using var outStr = File.Create(outPath); // Convert the image to a tagged PDF/A document using var outDoc = new Converter().Convert(inDoc, outStr, profile); ``` **Java:** ```java // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the image to a tagged PDF/A document com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile); ``` ## Full example **.NET:** ```csharp // Open image document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create the profile that defines the conversion parameters. // The Archive profile converts images to PDF/A documents for archiving. var profile = new Profiles.Archive(); // Set conformance of output document to PDF/A-2a profile.Conformance = new Conformance(2, Conformance.PdfALevel.A); // For PDF/A level 2a, an alternate text is required for each page of the image. // This is optional for other PDF/A levels, e.g. PDF/A-2b. profile.Language = "en"; profile.AlternateText.Add(alternateText); // Create output stream using var outStr = File.Create(outPath); // Convert the image to a tagged PDF/A document using var outDoc = new Converter().Convert(inDoc, outStr, profile); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts images to PDF/A documents for archiving. Archive profile = new Archive(); // Set conformance of output document to PDF/A-2a profile.setConformance(new Conformance(new Conformance.PdfAVersion(2, Level.A))); // For PDF/A level A, an alternate text is required for each page of the image. // This is optional for other PDF/A levels, e.g. PDF/A-2b. profile.setLanguage("en"); profile.getAlternateText().add(alternateText); // Optionally, other profile parameters can be changed according to the // requirements of your conversion process. try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr); // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the image to a tagged PDF/A document com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile)) { } ``` --- ## Archive a PDF document to PDF/A The Pdftools SDK lets you archive a PDF document so that it meets a defined PDF/A standard and conformance level, making the minimum changes necessary to the PDF structure and objects so it complies. It provides detailed information about any changes that were made during the conversion process. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/ValidateConvert)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/ValidateConvert)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/ValidateConvert)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/ValidateConvert)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/ValidateConvert)**. The Pdftools SDK supports conversion to the following PDF/A standards: - PDF/A-1 (ISO 19005-1) - PDF/A-2 (ISO 19005-2) - PDF/A-3 (ISO 19005-3) Within the PDF/A standards, the following conformance levels are supported: - B (Basic) - U (Unicode, only PDF/A-2 and PDF/A-3) - A (Accessibility) **info: For more information about supported PDF/A standards, review [PDF/A overview](https://www.pdf-tools.com/docs/knowledge/pdf-a/).** **Steps to archive a document**: 1. [Read the input document](#read-the-input-document) 2. [Create a Conformance object](#create-a-conformance-object) 3. [Create a Validator object](#create-a-validator-object) 4. [Run the Analyze method](#run-the-analyze-method) 5. [Create a Converter object](#create-a-converter-object) 6. [Run the Convert method](#run-the-convert-method) 7. [Check the conversion results](#check-the-conversion-results) 8. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input document First you need to read the PDF document you want to archive. To do this, load the input document from the file system into a read-only PDF `Document`. This `Document` can then later be passed to the `Validator` and `Converter`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); ``` ## Create a Conformance object The document conversion process begins with the creation of a `Conformance` object. The `Conformance` object defines the PDF/A standard and level to which the output document must conform. This example uses the PDF/A-2 standard (`2`), with conformance level B (`Conformance.PdfALevel.B`). **.NET:** ```csharp // Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion. // Here, PDF/A-2b is specified. Conformance conformance = new Conformance(2, Conformance.PdfALevel.B); ``` **Java:** ```java // Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion. // Here, PDF/A-2b is specified. Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B)); ``` ## Create a Validator object The `Validator` object analyzes the conformance of the input PDF document with the PDF/A standard and level defined in the `Conformance` object. This step is similar to the first step of the [PDF/A validation process](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/validate-a-pdf). However, during the PDF/A conversion process, additional information is also generated about the _potential_ conformance level of the document. **.NET:** ```csharp // Create the Validator object, and use the Conformance object to create // an AnalysisOptions object that controls the behavior of the Validator. var validator = new Validator(); var analysisOptions = new AnalysisOptions() { Conformance = conformance }; ``` **Java:** ```java // Create the Validator object, and use the Conformance object to create // an AnalysisOptions object that controls the behavior of the Validator. Validator validator = new Validator(); AnalysisOptions analysisOptions = new AnalysisOptions(); analysisOptions.setConformance(conformance); ``` ## Run the Analyze method In addition to evaluating the document's conformance with the defined PDF/A standard and level, the `Analyze` method also provides a recommendation on whether the input document _should_ be converted to PDF/A. The `Analyze` method recommends conversion in the following cases: - If `IsConforming` is `false`, that is, if the document does not conform to the required `Conformance`. - If the document is conforming, but there are other issues where conversion is highly recommended. For example, if corner-cases of the PDF/A specification that are known to cause problems for PDF viewers are detected. When conversion is recommended, the recommended output PDF/A standard and level is provided in the `RecommendedConformance` value of the `AnalysisResult` object. This `RecommendedConformance` is the highest possible PDF/A level to which the document can conform. Setting a higher level for the conversion typically results in a conformance exception. Even if the `RecommendedConformance` is higher than the `Conformance` passed to the `AnalysisOptions`, you do not need to increase the level of the `Conformance` passed to the `ConversionOptions`, because this level is automatically updated to the highest achievable level. Therefore, you can always set the `Conformance` provided in the `AnalysisOptions` to the lowest acceptable level. **.NET:** ```csharp // Run the analysis, and check the results. // Only proceed if conversion is recommended. var analysisResult = validator.Analyze(inDoc, analysisOptions); if (!analysisResult.IsConversionRecommended) { Console.WriteLine($"No conversion required for document with conformance {inDoc.Conformance}."); return; } ``` **Java:** ```java // Run the analysis, and check the results. // Only proceed if conversion is recommended. AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions); if (!analysisResult.getIsConversionRecommended()) { System.out.println("No conversion required for document with conformance " + inDoc.getConformance() + "."); return; } ``` ## Create a Converter object The `Converter` object converts the input PDF document into an output document that conforms to the defined PDF/A standard and level. When the `Converter` makes changes to the document during the conversion process, it emits `ConversionEvent` events that provide detailed information about the type of change and where the change has been made in the output PDF/A document. Even if the output document meets all required standards, the conversion may have resulted in differences that are acceptable in some processes, but not in others. Because of this, a handler function should listen to the `ConversionEvent` events and execute business logic based on the information contained in them. Each `ConversionEvent` has a `Severity` that indicates the following types of changes were made to the output document: 1. **Information:** Changes were made, but the change had no visible impact on the document. 2. **Warning:** Changes were made that may have visible impacts. Check the output file to decide if the result is acceptable. 3. **Error:** Changes were not successful. The document could not be converted to the desired conformance level. You should check for the highest `EventSeverity` that occurred during the conversion, as it makes it easier to troubleshoot errors later. **.NET:** ```csharp // Create a converter object var converter = new Converter(); // Add handler for conversion events var eventsSeverity = EventSeverity.Information; converter.ConversionEvent += (s, e) => { // Get the event's suggested severity var severity = e.Severity; // Optionally, the suggested severity can be changed according to // the requirements of your conversion process and, for example, // the event's category (e.Category). if (severity > eventsSeverity) eventsSeverity = severity; // Report conversion event Console.WriteLine("- {0} {1}: {2} ({3}{4})", severity.ToString()[0], e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : "" ); }; ``` **Java:** ```java // Create a converter object Converter converter = new Converter(); // Add handler for conversion events class EventListener implements ConversionEventListener { private EventSeverity eventsSeverity = EventSeverity.INFORMATION; public EventSeverity getEventsSeverity() { return eventsSeverity; } @Override public void conversionEvent(ConversionEvent event) { // Get the event's suggested severity EventSeverity severity = event.getSeverity(); // Optionally, the suggested severity can be changed according to // the requirements of your conversion process and, for example, // the event's category (e.Category). if (severity.ordinal() > eventsSeverity.ordinal()) eventsSeverity = severity; // Report conversion event System.out.format("- %c %s: %s (%s%s)%n", severity.toString().charAt(0), event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " on page " + event.getPageNo() : ""); } } EventListener el = new EventListener(); converter.addConversionEventListener(el); ``` ## Run the Convert method After generating the `AnalysisResult` and creating the `Converter` objects, the final step is to call the `Convert` method. By default, the `Converter` object attempts to convert the input PDF document to the PDF/A standard and level defined in the `RecommendedConformance` value in the `AnalysisResult`. It is possible to override this behavior and force conversion to a different PDF/A standard and level. You can force conversion by passing an optional `ConversionOptions` parameter to the `Convert` method. When `ConversionOptions` are passed to the `Convert` method but the required conformance level cannot be achieved, conversion aborts with a `ConformanceException`. **.NET:** ```csharp // Create a stream for the output PDF/A file. using var outStr = File.Create(outPath); // Convert the input document to the recommended conformance level using the converter object. using var outDoc = converter.Convert(analysisResult, inDoc, outStr); ``` **Java:** ```java // Create a stream for the output PDF/A file. FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the input document to the recommended conformance level using the converter object. Document outDoc = converter.convert(analysisResult, inDoc, outStr); ``` ## Check the conversion results If you plan to perform further processing, you may want to check the result of the conversion first. The overall success can be read from the highest `EventSeverity` that has been collected by the event handler during the conversion: **.NET:** ```csharp // Check if critical conversion events occurred switch (eventsSeverity) { case EventSeverity.Information: Console.WriteLine(\$"Successfully converted document to {outDoc.Conformance}."); break; case EventSeverity.Warning: Console.WriteLine(\$"Warnings occurred during the conversion of document to {outDoc.Conformance}."); Console.WriteLine(\$"Check the output file to decide if the result is acceptable."); break; case EventSeverity.Error: throw new Exception(\$"Unable to convert document to {conformance} because of critical conversion events."); } ``` **Java:** ```java // Check if critical conversion events occurred switch (el.getEventsSeverity()) { case INFORMATION: System.out.println("Successfully converted document to " + outDoc.getConformance() + "."); break; case WARNING: System.out.println("Warnings occurred during the conversion of document to " + outDoc.getConformance() + "."); System.out.println("Check the output file to decide if the result is acceptable."); break; case ERROR: throw new Exception("Unable to convert document to " + conformance + " because of critical conversion events."); } ``` Here's an example of the output that is generated by this sample code: ``` - Information: ManagedColors: Created calibrated color space substitute for DeviceRGB. (content of page 1) Successfully converted document to PDF/A-2u. ``` ### Full example **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion. // Here, PDF/A-2b is specified. var conformance = new Conformance(2, Conformance.PdfALevel.B); // Create the Validator object, and use the Conformance object to create // an AnalysisOptions object that controls the behavior of the Validator. var validator = new Validator(); var analysisOptions = new AnalysisOptions() { Conformance = conformance }; // Run the analysis, and check the results. // Only proceed if conversion is recommended. var analysisResult = validator.Analyze(inDoc, analysisOptions); if (!analysisResult.IsConversionRecommended) { Console.WriteLine($"No conversion required for document with conformance {inDoc.Conformance}."); return; } // Create a converter object var converter = new Converter(); // Add handler for conversion events var eventsSeverity = EventSeverity.Information; converter.ConversionEvent += (s, e) => { // Get the event's suggested severity var severity = e.Severity; // Optionally the suggested severity can be changed according to // the requirements of your conversion process and, for example, // the event's category (e.Category). if (severity > eventsSeverity) eventsSeverity = severity; // Report conversion event Console.WriteLine("- {0} {1}: {2} ({3}{4})", severity.ToString()[0], e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : "" ); }; // Create stream for output file using var outStr = File.Create(outPath); // Convert the input document to PDF/A using the converter object // and its conversion event handler using var outDoc = converter.Convert(analysisResult, inDoc, outStr); // Check if critical conversion events occurred switch (eventsSeverity) { case EventSeverity.Information: Console.WriteLine($"Successfully converted document to {outDoc.Conformance}."); break; case EventSeverity.Warning: Console.WriteLine($"Warnings occurred during the conversion of document to {outDoc.Conformance}."); Console.WriteLine($"Check the output file to decide if the result is acceptable."); break; case EventSeverity.Error: throw new Exception($"Unable to convert document to {conformance} because of critical conversion events."); } ``` **Java:** ```java // Open input document try (FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr)) { // Create a Conformance object that specifies the PDF/A level against which the document is to be validated prior to conversion. // Here, PDF/A-2b is specified. Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B)); // Create the Validator object, and use the Conformance object to create // an AnalysisOptions object that controls the behavior of the Validator. Validator validator = new Validator(); AnalysisOptions analysisOptions = new AnalysisOptions(); analysisOptions.setConformance(conformance); // Run the analysis, and check the results. // Only proceed if conversion is recommended. AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions); if (!analysisResult.getIsConversionRecommended()) { System.out.println("No conversion required for document with conformance " + inDoc.getConformance() + "."); return; } // Create output stream try (FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW)) { // Create a converter object Converter converter = new Converter(); // Add handler for conversion events class EventListener implements ConversionEventListener { private EventSeverity eventsSeverity = EventSeverity.INFORMATION; public EventSeverity getEventsSeverity() { return eventsSeverity; } @Override public void conversionEvent(ConversionEvent event) { // Get the event's suggested severity EventSeverity severity = event.getSeverity(); // Optionally, the suggested severity can be changed according to // the requirements of your conversion process and, for example, // the event's category (e.Category). if (severity.ordinal() > eventsSeverity.ordinal()) eventsSeverity = severity; // Report conversion event System.out.format("- %c %s: %s (%s%s)%n", severity.toString().charAt(0), event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " on page " + event.getPageNo() : ""); } } EventListener el = new EventListener(); converter.addConversionEventListener(el); // Convert the input document to PDF/A using the converter object // and its conversion event handler try (Document outDoc = converter.convert(analysisResult, inDoc, outStr)) { // Check if critical conversion events occurred switch (el.getEventsSeverity()) { case INFORMATION: System.out.println("Successfully converted document to " + outDoc.getConformance() + "."); break; case WARNING: System.out.println("Warnings occurred during the conversion of document to " + outDoc.getConformance() + "."); System.out.println("Check the output file to decide if the result is acceptable."); break; case ERROR: throw new Exception("Unable to convert document to " + conformance + " because of critical conversion events."); } } } } ``` :::note[Converting signed documents] If you convert a signed PDF to PDF/A, any signatures present in the document are removed before conversion. Therefore, if you need to include a signature in a PDF/A conformant document, first convert to PDF/A and then **[sign the document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document)**. --- ## Archive PDF document to TIFF image archive Convert a PDF document into a TIFF image suitable for a specific purpose, such as archiving, digital viewing, or faxing. You can adjust the conversion profile to suit the specific requirements of the document workflow. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Pdf2ImgSimple)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Pdf2ImgSimple)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Pdf2ImgSimple)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Pdf2ImgSimple)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Pdf2ImgSimple)**. **info: For more information about PDF to image conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#pdf-to-image-conversion-profiles).** **Steps to archive a document** 1. [Read the input document](#read-the-input-document) 2. [Select a conversion profile](#select-a-conversion-profile) 3. [Adjust the conversion profile](#adjust-the-conversion-profile) 4. [Convert the document to an image](#convert-the-document-to-an-image) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input document First you need to read the PDF document you want to archive. To do this, load the input document from the file system into a (read-only) PDF `Document`. This `Document` can then later be passed to the `Converter`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); ``` ## Select a conversion profile You start the conversion process by creating a conversion `Profile` object. The `Profile` object defines the parameters that are applied to the conversion process. This example uses the `Archive` profile, which is intended for document workflows that generate an output for archiving in TIFF image format. **.NET:** ```csharp // Create a profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. var profile = new Profiles.Archive(); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. Archive profile = new Archive(); ``` ## Adjust the conversion profile The default conversion `Profile` settings are sufficient for most document workflows. If the document workflow has specific requirements (for example, the use of a specific compression algorithm), you can adjust the properties of the conversion `Profile` directly. For more information about PDF to image conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#pdf-to-image-conversion-profiles). ## Convert the document to an image After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `ConvertDocument` method. The output image file is created at the specified path. **.NET:** ```csharp // Create output stream using var outStr = File.Create(outPath); // Convert the PDF document to an image document using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the PDF document to an image document com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile); ``` ## Full example **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a profile that defines the initial conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. var profile = new Profiles.Archive(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. // Create output stream using var outStr = File.Create(outPath); // Convert the PDF document to an image document using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. Archive profile = new Archive(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the PDF document to an image document com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile)) { } ``` --- ## Merge and split PDF documents The Pdftools SDK lets you assemble pages from one or more input PDF documents and images into any combination of output PDF documents and images. It offers complete control over the generated documents by providing copying options that you can configure to your needs. The Pdftools SDK features fast performance and efficient memory usage, making it ideal for processing large batches of documents and time-sensitive processes. ## Merge documents Merge multiple PDF files and images into a single output PDF document using the `DocumentAssembler` class of the Pdftools SDK. For example, convert a portfolio of documents and images a customer uploaded into a single output PDF document, suitable for further processing and archiving. During this process, duplicated resources such as fonts are identified and merged, significantly reducing the size of the output PDF document. The `DocumentAssembler` class automatically resolves conflicts between named elements like form fields. :::tip[Get started] Learn to merge multiple PDF documents and images into one output PDF document on the **[Merge PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/assemble/merge-pdfs)** page. ## Split documents Split a single PDF document into multiple output PDF documents and images using the `DocumentAssembler` class of the Pdftools SDK. For example, you can split an input PDF document, in which every page represents an invoice for a different customer into multiple output PDF documents with one output document for each customer. During this process, only the resources required by each page are copied to the output document containing that page, ensuring that PDF documents do not have redundant or potentially sensitive information. :::tip[Get started] Learn to split one input PDF document into multiple output PDF documents on the **[Split a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/assemble/split-a-pdf)** page. ## Merge and split combined You can also split and re-merge multiple input documents into numerous output documents simultaneously, allowing you to efficiently assemble documents without the hassle of temporary files representing intermediate states of the process. --- ## Merge PDF documents The Pdftools SDK lets you assemble pages from multiple input PDF documents into a single output PDF document. During this process, duplicated resources such as fonts are identified and merged, significantly reducing the size of the output PDF document. The `DocumentAssembler` class automatically resolves conflicts between named elements like form fields. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Merge)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Merge)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Merge)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Merge)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Merge)**. **.NET:** Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process. **Java:** Depending on the requirements, you can adjust the characteristics of the output document by setting the Class PageCopyOptions used in the assembly process. You can also add images to the output document by [converting an image to a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/convert-image-pdf) and then merging the converted image into the output PDF document. **Steps to merge PDF documents**: 1. [Create a DocumentAssembler object](#create-a-documentassembler-object) 2. [Read the input documents](#read-the-input-documents) 3. [Append to the output document](#append-to-the-output-document) 4. [Run the Assemble method](#run-the-assemble-method) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Create a DocumentAssembler object Create the `DocumentAssembler` object. This object will generate the output PDF document. Instantiate the `DocumentAssembler` and pass it an output `Stream` (for example, a file or memory stream) that will contain the output data. **.NET:** ```csharp // Open an output stream and pass it to the DocumentAssembler using var outStream = File.Create(outPath); using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream); ``` **Java:** ```java // Open an output stream and pass it to the DocumentAssembler FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); DocumentAssembler docAssembler = new DocumentAssembler(outStream)) { ``` ## Read the input documents Iterate through the input document set, loading each file as a `Document`. **.NET:** ```csharp // Iterate through the set of input PDF documents foreach (var inPath in inPaths) { using var inStream = File.OpenRead(inPath); using var inDoc = PdfTools.Pdf.Document.Open(inStream); ``` **Java:** ```java // Iterate through the set of input PDF documents for (String inPath : inPaths) { FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); ``` ## Append to the output document Select a page range from the input `Document` by passing optional `firstPage` and `lastPage` parameters to the `Append` method of the `DocumentAssembler` object. If these parameters are not passed, the entire input `Document` is appended to the output PDF document. This example uses the default parameters, so the entire input `Document` is appended. **.NET:** ```csharp // Append the entire content of each input document to the output document // Optionally, firstPage and lastPage parameters can be passed to append only a range of pages docAssembler.Append(inDoc); ``` **Java:** ```java // Append the entire content of each input document to the output document // Optionally, firstPage and lastPage parameters can be passed to append only a range of pages docAssembler.append(inDoc); ``` ## Run the Assemble method After using the `Append` method to merge the input documents into the output PDF document, the final step is to call the `Assemble` method. This method creates the structure of the output PDF document and writes the document to the output `Stream` of the `DocumentAssembler` object. **.NET:** ```csharp // Create the final structure of the output PDF document and write it to the output stream docAssembler.Assemble(); ``` **tip: Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/dotnet-notes#idisposable-objects).** **Java:** ```java // Create the final structure of the output PDF document and write it to the output stream docAssembler.assemble(); ``` **tip: Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/java-notes#autocloseable-objects).** ## Full example **.NET:** ```csharp // Create output stream using var outStream = File.Create(outPath); using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream); // Iterate through the set of input PDF documents foreach (var inPath in inPaths) { using var inStream = File.OpenRead(inPath); using var inDoc = PdfTools.Pdf.Document.Open(inStream); // Append the entire content of each input document to the output document docAssembler.Append(inDoc); } // Create the final structure of the output PDF document and write it to the output stream docAssembler.Assemble(); ``` **Java:** ```java try ( // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); DocumentAssembler docAssembler = new DocumentAssembler(outStream)) { // Iterate through the set of input PDF documents for (String inPath : inPaths) { try ( FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr)) { // Append the entire content of each input document to the output document docAssembler.append(inDoc); } } // Create the final structure of the output PDF document and write it to the output stream docAssembler.assemble(); } ``` --- ## Split PDF document The Pdftools SDK lets you split a single input PDF document into multiple output PDF documents and images. During this process, only the resources required by each page are copied to the output document containing that page. This ensures your output PDF files do not contain redundant or potentially sensitive information. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Split)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Split)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Split)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Split)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Split)**. **.NET:** Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process. **Java:** Depending on the requirements, you can adjust the characteristics of the output document by setting the Class PageCopyOptions used in the assembly process. You can also generate the output documents as images by [converting a PDF document to an image](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/convert-pdf-image). **Steps to split PDF documents**: 1. [Open the input Document](#open-the-input-document) 2. [Create the DocumentAssembler object](#create-the-documentassembler-object) 3. [Append to the output document](#append-to-the-output-document) 4. [Run the Assemble method](#run-the-assemble-method) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Open the input Document Read the PDF document you want to convert. To do this, load the input document from the file system into a (read-only) PDF `Document`. **.NET:** ```csharp // Open input document using var inStream = File.OpenRead(inPath); using var inDoc = PdfTools.Pdf.Document.Open(inStream); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr)) { ``` ## Create the DocumentAssembler object Create the `DocumentAssembler` object that will generate the output PDF document. To do this, instantiate the `DocumentAssembler` and pass it an output `Stream` (for example, a file or memory stream) that will contain the output data. The following example creates one output PDF document for each input document page. **.NET:** ```csharp // Repeat for each page in the input document for (int i = 1; i <= inDoc.PageCount; ++i) { // Create the output stream and pass it to the document assembler using var outStream = File.Create(outPathPrefix + "_page_" + i + ".pdf"); using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream); ``` **Java:** ```java // Repeat for each page in the input document for (int i = 1; i <= inDoc.getPageCount(); ++i) { // Create the output stream and pass it to the document assembler FileStream outStream = new FileStream(outPathPrefix + "_page_" + i + ".pdf", FileStream.Mode.READ_WRITE_NEW); DocumentAssembler docAssembler = new DocumentAssembler(outStream); ``` ## Append to the output document You can select a page range to copy from the input `Document` by passing `firstPage` and `lastPage` parameters to the `Append` method of the `DocumentAssembler` object. In this example, we only append the current page of the input PDF document to each output document. **.NET:** ```csharp // Append the current page of the input PDF document to a single-page output document docAssembler.Append(inDoc, i, i); ``` **Java:** ```java // Append the current page of the input PDF document to a single-page output document docAssembler.append(inDoc, i, i); ``` ## Run the Assemble method After using the `Append` method to add the required pages to the output PDF document, the final step is to call the `Assemble` method. This method creates the structure of the output PDF document and writes the document to the output `Stream` of the `DocumentAssembler` object. **.NET:** ```csharp // Create the final structure of the output PDF document and write it to the output stream docAssembler.Assemble(); ``` **tip: Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/dotnet-notes#idisposable-objects).** **Java:** ```java // Create the final structure of the output PDF document and write it to the output stream docAssembler.assemble(); ``` **tip: Don't forget that some objects (like the `Document` object) must be explicitly closed. For these objects, we recommend using the mechanism for [automatically closing objects](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/java-notes#autocloseable-objects).** ## Full example **.NET:** ```csharp // Open input document using var inStream = File.OpenRead(inPath); using var inDoc = PdfTools.Pdf.Document.Open(inStream); // Repeat for each page in the input document for (int i = 1; i <= inDoc.PageCount; ++i) { // Create the output stream and pass it to the document assembler using var outStream = File.Create(outPathPrefix + "_page_" + i + ".pdf"); using var docAssembler = new PdfTools.DocumentAssembly.DocumentAssembler(outStream); // Append the current page of the input PDF document to the output document docAssembler.Append(inDoc, i, i); // Create the final structure of the output PDF document and write it to the output stream docAssembler.Assemble(); } ``` **Java:** ```java try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr)) { for (int i = 1; i <= inDoc.getPageCount(); ++i) { try ( // Create output stream for each page of the input document FileStream outStream = new FileStream(outPathPrefix + "_page_" + i + ".pdf", FileStream.Mode.READ_WRITE_NEW); DocumentAssembler docAssembler = new DocumentAssembler(outStream)) { docAssembler.append(inDoc, i, i); docAssembler.assemble(); } } } ``` --- ## Convert with the Pdftools SDK With the Pdftools SDK you can convert various file formats: - [Convert images to PDF](#convert-images-to-pdf) - [Convert a PDF document to image](#convert-pdfs-to-images) --- ## Convert PDFs to images Create single-­page and multi­-page image files and rasterized PDF documents from PDF documents. Specify how PDFs are converted to images, choosing the resolution, quality in lossy image compression, as well as the color space and depth to be used. Convert PDFs to TIFF-F suitable for fax transmission using the [Fax conversion profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#fax). :::note[Accepted formats] | Input | Output | | ------------------------------------------- | --------------- | | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | TIFF, PNG, JPEG | **Image processing** - Set resolution (DPI) - Set TIFF file compression algorithm - Set the quality of lossy image compression **Color management** - Set background color - Set color space **Page layout** - Define page dimensions in standard page sizes, points or pixels - Set rotation: force portrait or landscape or inherit rotation from original document :::tip[Get started] Learn how to **[convert a PDF document to an image](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/convert-pdf-image)**. --- ## Convert images to PDF Convert one or more single-page or multi-page raster images into an output PDF document. Use default [image to PDF conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#image-to-pdf-conversion-profiles) to automatically process image conversion. Specify how the images are processed, selecting compression level, image quality, and resolution. Choose the formatting of the output document, including page size, area, scaling, and image position and orientation. Determine the conformance level of the output PDF document, and set additional document settings such as attributes, permissions, alternative text. :::note[Accepted formats] | Input | Output | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | BMP, GIF, JBIG2, JPEG, JPEG2000, JPEG-LS, PBM, PNG, TIFF, LZW, CCITT | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-1b, PDF/A-2, PDF/A-2b, PDF/A-2u, PDF/A-3, PDF/A-3b, PDF/A-3u | **Image processing** - Select image compression, depending on the image type - Select image quality for lossy compression - Set standard resolution (DPI / X and Y coordinates) - Choose optional JPEG image recompression - Support for image masks and mixed raster content (MRC) **Page layout** - Select PDF page size or determine automatically - Select page area - Set scaling - Set image position - Set image orientation (portrait or landscape) **PDF document settings** - Set encryption and user access permissions - Set document attributes - Select and embed ICC color profiles - Embed XMP metadata :::tip[Get started] Learn how to **[convert an image to a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/convert-image-pdf)**. --- --- ## Conversion profiles Conversion profiles define how an input file is converted and rendered in an output file. A profile contains a set of conversion parameters that are combined for a practical use case. For example, creating documents for viewing, archiving, or sending via fax. Although a conversion profile provides default parameters for a specific use case, most of the parameters of a conversion profile can be adjusted to suit the specific requirements of a document workflow. The Pdftools SDK provides two types of conversion profile: - **[PDF to image conversion profiles](#pdf-to-image-conversion-profiles)**: used when converting PDF documents to images. - **[Image to PDF conversion profiles](#image-to-pdf-conversion-profiles)**: used when converting images to PDF documents. --- ## PDF to image conversion profiles PDF to image conversion profiles provide a set of default parameters that are used when converting PDF documents to images. The Pdftools SDK provides three image conversion profiles: - [Viewing](#viewing) - [Archive](#archive) - [Fax](#fax) ### Viewing The `Viewing` profile is used to convert PDFs to rasterized JPEG or PNG images for use in web and desktop viewing applications, or for use as thumbnails. For JPEG and PNG images, the default output uses the RGB color space, has a resolution of 150 DPI, and is rendered on a white background. For PNG images, a lossless compression algorithm is applied. For JPEG images, JPEG compression is applied with a default quality factor of 85. The following options may also be used: - **Quality factor (JPEG)**: 0 - 100 - **Color space (JPEG)**: RGB, CMYK or gray - **Color space (PNG)**: RGB or gray - **Background**: Transparent or white - **Resolution**: DPI (0.0 - 10,000.0) or as a maximum image size (in pixels) ### Archive The `Archive` profile is used to convert PDF documents to TIFF images for archiving as rasterized images. By default, the output image inherits the color space of the PDF document, has a resolution of 300 DPI, and uses the LZW compression algorithm. The following options may also be used: - **Compression algorithm**: LZW, JPEG or flate - **Color space**: inherit the color space of the PDF document, RGB, CMYK or gray - **Resolution**: 0.0 - 10,000.0 DPI ### Fax The `Fax` profile is designed for converting PDFs into TIFF-F conforming rasterized images for fax transmission. The output format is a multi-page TIFF file, which contains all PDF pages converted into rasterized images. By default, the output images are scaled to a width of 1728 pixels, with a horizontal resolution of 204 DPI, and a vertical resolution of 98 DPI. Dithering converts all colors and grayscale tones to bitonal. The output image is compressed using the CCITT Group 3 compression algorithm. You can use the following options: - **Compression algorithm**: CCITT Group 3 or CCITT Group 4 - **Vertical resolution**: 98 DPI (Standard) or 196 DPI (High) - **Dithering mode**: Algorithm used when converting color or grayscale pixels to bitonal: - `Halftone`: Ordered (clustered-dot) halftoning. The default; produces a repeating pattern that is well suited to fax transmission and laser reproduction. - `None`: No dithering; pixels are mapped to black or white by a fixed threshold. Produces the smallest files and the sharpest edges, but loses tonal information. - `FloydSteinberg`: Floyd‑Steinberg error-diffusion dithering. General-purpose tonal reproduction. - `Atkinson`: Atkinson error-diffusion dithering. Preserves local contrast in photographs better than Floyd‑Steinberg at the cost of some shadow detail. --- ## Image to PDF conversion profiles Image to PDF conversion profiles provide a set of default parameters that are used when converting images to PDF documents. The Pdftools SDK provides two image conversion profiles: - [Default](#default) - [Archive](#archive-1) ### Default The `Default` profile is used for document workflows that need to convert images to PDF documents, but do not have long-term archiving or accessibility requirements. By default, the images are placed onto A4-sized (210 mm x 297 mm) pages in portrait orientation with 20 mm (0.79 in) margins. Large images are scaled down to fit the page. The PDF conformance level is set to [PDF 1.7](https://www.pdf-tools.com/docs/knowledge/pdf-standards#pdf-17-iso-32000-1). The following options may also be used: - **Scaling options**: Import all images in portrait orientation, automatically detect scaling based on image dimensions, or automatically detect scaling based on image type - **Page dimensions**: standard (A3, A4, A5, Letter, Legal) or custom page sizes, in portrait or landscape orientation - **Page margins**: Standard or custom page margins - **PDF conformance**: PDF 1.x or [PDF 2.0](https://www.pdf-tools.com/docs/knowledge/pdf-standards#pdf-20-iso-32000-2) ### Archive The `Archive` profile is designed for document workflows that need to convert images to PDF documents, and comply with long-term archiving or document accessibility requirements. By default, the output of the `Archive` profile matches the output of the `Default` profile, except that the default PDF conformance level for the `Archive` profile is set to [PDF/A-2b](https://www.pdf-tools.com/docs/knowledge/pdf-a/#pdfa-2). The same options apply to the `Archive` profile as to the `Default` profile. However, the following additional options are available: - **PDF conformance**: PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2u, PDF/A-2a, PDF/A-3b, PDF/A-3u, or PDF/A-3a - **Accessible content**: Provide language and alternate text for each imported image (required for level A conformance) **tip: For PDF/A-1a, PDF/A-2a, and PDF/A-3a conformance, accessible content must be provided.** For more information about creating accessible PDF documents, see **[Convert image to Accessible PDF](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-image-pdfa-accessible)**. --- ## Convert an image to a PDF document Convert one or more TIFF, JPEG, BMP, GIF, PNG, JBIG2, or JPEG2000 images into an output PDF document. Content for long-term archiving and document accessibility can be added during the conversion process. The formatting and conformance level of the output PDF document can be adjusted to suit the requirements of the document workflow. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Img2PdfDefault)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Img2PdfDefault)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Img2PdfDefault)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Img2PdfDefault)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Img2PdfDefault)**. **Steps to convert a document** 1. [Read the input image](#read-the-input-image) 2. [Select a conversion profile](#select-a-conversion-profile) 3. [Adjust the conversion profile](#adjust-the-conversion-profile) 4. [Convert the image to a PDF document](#convert-the-image-to-a-pdf-document) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input image First you need to read the image you want to convert. To do this, load the input image from the file system into a read-only image `Document`. This `Document` can then later be passed to the `Converter`. **.NET:** ```csharp // Open image document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr); ``` ## Select a conversion profile You start the image conversion process by creating a conversion `Profile` object to determine the [conversion profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles). The `Profile` object defines the parameters that are applied to the conversion process. **tip: For more information about image to PDF conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#image-to-pdf-conversion-profiles).** This example uses the `Default` profile, which is designed for document workflows that need to convert images to PDF documents, but do not have long-term archiving or accessibility requirements. **.NET:** ```csharp // Create the profile that defines the conversion parameters. // The Default profile converts images to PDF documents. var profile = new Profiles.Default(); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Default profile converts images to PDF documents. Default profile = new Default(); ``` ## Adjust the conversion profile If the images must be added to the PDF document in a specific way (for example, if the image size should be preserved or a specific page orientation should be used), this can be achieved by changing the properties of the conversion profile. The PDF conformance level may also be adjusted in this way. For more information about image to PDF conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#image-to-pdf-conversion-profiles). ## Convert the image to a PDF document After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `Convert` method. The output PDF document is created at the specified path. **.NET:** ```csharp // Create output stream using var outStr = File.Create(outPath); // Convert the image to a PDF document using var outDoc = new Converter().Convert(inDoc, outStr, profile); ``` **Java:** ```java // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the image to a PDF document Document outDoc = new Converter().convert(inDoc, outStream, profile); ``` ## Full example **.NET:** ```csharp // Open image document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create the profile that defines the conversion parameters. // The Default profile converts images to PDF documents. var profile = new Profiles.Default(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. // Create output stream using var outStr = File.Create(outPath); // Convert the image to a PDF document using var outDoc = new Converter().Convert(inDoc, outStr, profile); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Default profile converts images to PDF documents. Default profile = new Default(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr); // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the image to a PDF document com.pdftools.pdf.Document outDoc = new Converter().convert(inDoc, outStream, profile)) { } ``` --- ## Convert a PDF document to an image Convert a PDF document into an output image suitable for a specific purpose, such as archiving, digital viewing, or faxing. The conversion profile can be adjusted to suit the specific requirements of the document workflow. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Pdf2ImgSimple)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Pdf2ImgSimple)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Pdf2ImgSimple)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Pdf2ImgSimple)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Pdf2ImgSimple)**. **info: For more information about PDF to image conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#pdf-to-image-conversion-profiles).** **Steps to convert a document** 1. [Read the input document](#read-the-input-document) 2. [Select a conversion profile](#select-a-conversion-profile) 3. [Adjust the conversion profile](#adjust-the-conversion-profile) 4. [Convert the document to an image](#convert-the-document-to-an-image) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input document First you need to read the PDF document you want to convert. To do this, load the input document from the file system into a (read-only) PDF `Document`. This `Document` can then later be passed to the `Converter`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); ``` ## Select a conversion profile You start the conversion process by creating a conversion `Profile` object. The `Profile` object defines the parameters that are applied to the conversion process. This example uses the `Archive` profile, which is intended for document workflows that generate an output for archiving in TIFF image format. **.NET:** ```csharp // Create a profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. var profile = new Profiles.Archive(); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. Archive profile = new Archive(); ``` ## Adjust the conversion profile The default conversion `Profile` settings are sufficient for most document workflows. If the document workflow has specific requirements (for example, the use of a specific compression algorithm), you can adjust the properties of the conversion `Profile` directly. For more information about PDF to image conversion profiles, see [Conversion profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#pdf-to-image-conversion-profiles). ## Convert the document to an image After creating the `Profile` object and adjusting for any workflow-specific properties, the final step is to instantiate a `Converter` object and call its `ConvertDocument` method. The output image file is created at the specified path. **.NET:** ```csharp // Create output stream using var outStr = File.Create(outPath); // Convert the PDF document to an image document using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the PDF document to an image document com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile); ``` ## Full example **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a profile that defines the initial conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. var profile = new Profiles.Archive(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. // Create output stream using var outStr = File.Create(outPath); // Convert the PDF document to an image document using var outDoc = new Converter().ConvertDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create the profile that defines the conversion parameters. // The Archive profile converts PDF documents to TIFF images for archiving. Archive profile = new Archive(); // Optionally, the profile's parameters can be changed according to the // requirements of your conversion process. try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); // Create output stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Convert the PDF document to an image document com.pdftools.image.Document outDoc = new Converter().convertDocument(inDoc, outStream, profile)) { } ``` --- ## Embed e-invoice Learn how to embed e-invoices such as ZUGFeRD or Factur-X into PDF files using the Pdftools SDK, ensuring compliance with international e-invoicing standards. This guide outlines the key features and requirements for integrating e-invoices using the SDK. ## What are ZUGFeRD and Factur-X? ZUGFeRD and Factur-X are hybrid e-invoicing standards that combine human-readable PDF/A-3 documents with embedded XML data for automated processing. Originally developed in Germany, ZUGFeRD was later aligned with the French Factur-X standard as part of the Franco-German digital agenda. Both standards conform to the European norm EN 16931, making them suitable for cross-border invoicing within the European Union. Why use ZUGFeRD and Factur-X? For more details about why to use the e-invoice formats presented in this guide, review [ZUGFeRD - A standard for electronic invoices in PDF/A format](https://www.pdf-tools.com/pdf-knowledge/zugferd-standard-electronic-invoices/). :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Zugferd)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Zugferd)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Zugferd)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Zugferd)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Zugferd)**. ## PDF/A-3 Compliance and invoice embedding ZUGFeRD and Factur-X invoices require embedding structured XML data within a PDF/A-3 document. The Pdftools SDK integrates this process into its PDF-to-PDF/A conversion interface, ensuring the final document meets the necessary compliance requirements. As a result, invoices can only be embedded as part of a PDF/A-3 conversion. For information on converting any PDF into a PDF/A, review [Archive a PDF document to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa). ## Supported invoice formats and profiles The Pdftools SDK supports multiple versions and profiles of ZUGFeRD and Factur-X, including: - **ZUGFeRD 1.0**: Basic, Comfort, Extended - **ZUGFeRD 2.0** or **2.1**: Minimum, Basic WL, Basic, EN 16931, Extended, XRechnung - **Factur-X 1.0**: Minimum, Basic WL, Basic, EN 16931, Extended The Pdftools SDK automatically detects the invoice type and version, ensuring seamless integration into the PDF without requiring manual specification. ## XML invoice handling The SDK does not perform full validation of the invoice XML. Instead, it extracts key data elements necessary for correct integration into the PDF. The user's responsibility is to ensure the validity and correctness of the invoice XML. The SDK verifies specific fields to determine the invoice type and version but does not enforce full schema validation. --- ## OCR with the Pdftools SDK The Pdftools SDK includes a built-in OCR module that enhances PDF documents by making text searchable and extractable. The module takes a PDF as input, analyzes it with an OCR engine, and outputs a PDF with an invisible, selectable text layer. The visual appearance of the document is preserved. :::info[Pdftools OCR Service required] The OCR module requires a running [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) instance. For installation details, review [Set up Pdftools OCR Service with Pdftools SDK](https://www.pdf-tools.com/docs/ocr-service/getting-started/windows/set-up-with-sdk/). ## How it works The OCR module processes a PDF document through the following pipeline: 1. **Open document.** The input PDF is opened for reading. 1. **Process pages.** Each page is processed individually: 1. **Analyze page.** The page content is analyzed. The modes configured in image options, text options, and page options are evaluated to determine whether the OCR engine is required. 1. **OCR page** (if required). The page is rendered to an image at the optimal resolution, sent to the OCR engine, and results are received. 1. **Apply results.** OCR results are matched to the page content and applied according to each dimension's mode: - Results on images are processed by the image options mode. - Results matching existing text are processed by the text options mode. - Remaining results are added as page text if the page options mode is not `None`. 1. **Copy page.** The page is written to the output with OCR enhancements applied. 1. **Process embedded files** (optional). If `ProcessEmbeddedFiles` is enabled, embedded PDF files are processed recursively. A page is sent to the OCR engine only when required by the configured modes. Choosing modes carefully avoids unnecessary OCR operations, which improves performance. ## Processing dimensions The OCR module processes documents across three independent dimensions. You can use any combination of these to suit your workflow. ### Image OCR Image OCR recognizes text in scanned images within a PDF and adds an invisible text layer that makes the content searchable and selectable. | Mode | Description | |------|-------------| | `UpdateText` | Process only images that don't already have OCR text. Recommended for most scanned documents. | | `ReplaceText` | Re-OCR all images, replacing any existing text layer. | | `RemoveText` | Remove existing OCR text without re-processing. No OCR engine required. | | `IfNoText` | Process images only if the entire document contains no text. | ### Text OCR Text OCR fixes non-extractable text in born-digital PDFs. Some PDF fonts lack proper Unicode mappings, which prevents text from being copied or searched correctly. Text OCR determines the correct Unicode values for these characters. | Mode | Description | |------|-------------| | `Update` | Fix only text with missing or incorrect Unicode mappings. Recommended for most documents. | | `Replace` | Reprocess all text, even text that already has valid Unicode mappings. | ### Page OCR Page OCR processes entire pages and adds the results as OCR text. It can also add PDF tagging for accessibility compliance. | Mode | Description | |------|-------------| | `All` | Process all non-empty pages. | | `IfNoText` | Process only pages that have content but no text. | | `AddResults` | Don't trigger OCR independently, but add page-level results when OCR is triggered by image or text processing. | :::note[Accepted formats] | Input format | Output format | |---|---| | PDF 1.x, PDF 2.0, PDF/A-1, PDF/A-2, PDF/A-3 | PDF (same format preserved, PDF/A conformance maintained) | ## Use cases The three processing dimensions can be combined in different ways depending on your goal: - **Make scanned documents searchable.** Use image OCR (`UpdateText`) and text OCR (`Update`) to add a text layer to scanned pages and fix any non-extractable text. - **Fix non-extractable text in born-digital PDFs.** Use text OCR (`Update`) to correct Unicode mappings for fonts that don't provide proper encoding information. - **Tag scans for accessibility.** Use image OCR with page OCR tagging to prepare scanned documents for PDF/A level A conformance or PDF/UA accessibility requirements. - **Full document processing.** Use all three dimensions together to handle scanned images, non-extractable text, and page-level tagging in a single pass. **note: Pdftools SDK connects to Pdftools OCR Service for text recognition and produces enhanced PDFs. For comparison, Pdftools OCR Service outputs XML to be used with the Conversion Service.** :::tip[Get started] Learn how to **[OCR a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf)**. --- ## OCR a PDF document Apply OCR to a PDF document to make scanned content searchable and text extractable. The Pdftools SDK analyzes the document with an OCR engine and adds an invisible, selectable text layer while preserving the visual appearance. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/OcrDocument)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/OcrDocument)**, and **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/OcrDocument)**. **Steps to OCR a document**: 1. [Create the OCR engine](#create-the-ocr-engine) 1. [Open the input document](#open-the-input-document) 1. [Configure OCR options](#configure-ocr-options) 1. [Process the document](#process-the-document) 1. [Full example](#full-example) --- :::note[Before you begin] - [Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license). - Install and start [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/). Pdftools SDK connects to Pdftools OCR Service over HTTP for text recognition. The default endpoint is `http://localhost:7982/`. For installation details, review [Set up Pdftools OCR Service with Pdftools SDK](https://www.pdf-tools.com/docs/ocr-service/getting-started/windows/set-up-with-sdk/). ## Create the OCR engine Create an `Engine` instance by passing the engine name and connection parameters. The only supported engine is `service`, which connects to a running [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) instance over HTTP. Specify the engine name followed by `@` and the service URL. For example, `"service@http://localhost:7982/"` connects to an OCR Service at that URL. To connect to multiple instances, separate URLs with a semicolon (for example, `"service@http://host1:7982/;http://host2:7982/"`). After creating the engine, set the recognition languages as a comma-separated string (for example, `"German,English"`). You can also set engine-specific parameters using the `Parameters` property as semicolon-separated key-value pairs (for example, `"PredefinedProfile=Default"` or `"Profile=/path/to/custom-profile.ini"`). The engine can be reused across multiple documents. However, each `Engine` instance must only be used by one thread at a time. **.NET:** ```csharp // Create the OCR engine using var engine = Engine.Create(ocrEngineName); // Set the language(s) for OCR recognition (e.g. "German,English") engine.Languages = language; ``` **Java:** ```java // Create the OCR engine Engine engine = Engine.create(ocrEngineName); // Set the language(s) for OCR recognition (e.g. "German,English") engine.setLanguages(language); ``` **Python:** ```python # Create the OCR engine engine = Engine.create(ocr_engine_name) # Set the language(s) for OCR recognition (e.g. "German,English") engine.languages = language ``` **C:** ```c // Create the OCR engine pEngine = PdfToolsOcr_Engine_Create(szOcrEngineName); // Set the language(s) for OCR recognition (e.g. "German,English") PdfToolsOcr_Engine_SetLanguages(pEngine, szLanguage); ``` ## Open the input document Load the input PDF from the file system into a read-only `Document`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); ``` **Python:** ```python # Open input document in_stream = io.FileIO(input_path, 'rb') input_document = Document.open(in_stream) ``` **C:** ```c // Open input document pInStream = _tfopen(szInPath, _T("rb")); TPdfToolsSys_StreamDescriptor inDesc; PdfToolsSysCreateFILEStreamDescriptor(&inDesc, pInStream, 0); pInDoc = PdfToolsPdf_Document_Open(&inDesc, _T("")); ``` ## Configure OCR options Create an `OcrOptions` object and configure its three sub-objects: image options, text options, and page options. Each dimension controls a different aspect of OCR processing. ### Image options Image options control how scanned images within the PDF are processed. Set the `Mode` property to determine which images to OCR: - **`UpdateText`**: Process only images without existing OCR text. Recommended for most scanned documents. - **`ReplaceText`**: Re-OCR all images, replacing any existing text layer. Use this when the existing OCR results are poor. - **`RemoveText`**: Remove existing OCR text without re-processing. No OCR engine is required. - **`IfNoText`**: Process images only if the entire document contains no text at all. Additional image options: - **`RotateScan`**: Automatically detect and correct page rotation. - **`DeskewScan`**: Straighten skewed scans. - **`RemoveOnlyInvisibleOcrText`**: When using `ReplaceText` or `RemoveText`, only affect invisible OCR text (text rendering mode 3). Visible text that was placed manually is preserved. **.NET:** ```csharp var options = new OcrOptions(); // Configure image OCR: recognize text from scanned images options.ImageOptions.Mode = ImageProcessingMode.UpdateText; options.ImageOptions.RemoveOnlyInvisibleOcrText = true; options.ImageOptions.DeskewScan = true; options.ImageOptions.RotateScan = true; ``` **Java:** ```java OcrOptions options = new OcrOptions(); // Configure image OCR: recognize text from scanned images options.getImageOptions().setMode(ImageProcessingMode.UPDATE_TEXT); options.getImageOptions().setRemoveOnlyInvisibleOcrText(true); options.getImageOptions().setDeskewScan(true); options.getImageOptions().setRotateScan(true); ``` **Python:** ```python options = OcrOptions() # Configure image OCR: recognize text from scanned images options.image_options.mode = ImageProcessingMode.UPDATE_TEXT options.image_options.remove_only_invisible_ocr_text = True options.image_options.deskew_scan = True options.image_options.rotate_scan = True ``` **C:** ```c pOptions = PdfToolsOcr_OcrOptions_New(); // Configure image OCR: recognize text from scanned images pImageOptions = PdfToolsOcr_OcrOptions_GetImageOptions(pOptions); PdfToolsOcr_ImageOptions_SetMode(pImageOptions, ePdfToolsOcr_ImageProcessingMode_UpdateText); PdfToolsOcr_ImageOptions_SetRemoveOnlyInvisibleOcrText(pImageOptions, TRUE); PdfToolsOcr_ImageOptions_SetDeskewScan(pImageOptions, TRUE); PdfToolsOcr_ImageOptions_SetRotateScan(pImageOptions, TRUE); ``` ### Text options Text options control how non-extractable text in the PDF is processed. Some fonts lack proper Unicode mappings, which prevents text from being copied or searched correctly. - **`Update`**: Fix only text with missing or incorrect Unicode mappings. Recommended for most documents. - **`Replace`**: Reprocess all text, even text that already has valid Unicode mappings. Additional text options: - **`SkipMode`**: Skip specific font types during text processing. Values can be combined. Available flags: `KnownSymbolic` (skip symbolic fonts such as ZapfDingbats and Wingdings) and `PrivateUseArea` (skip text with Unicode Private Use Area code points). - **`UnicodeSource`**: Specify additional sources for Unicode mapping. Values can be combined. Available flags: `InstalledFont` (look up Unicode values from system-installed fonts), `KnownSymbolicPua` (use Private Use Area values for known symbolic fonts), and `FallbackAllPua` (use Private Use Area values as a fallback for all characters). **.NET:** ```csharp // Configure text OCR: update non-extractable text with correct Unicode options.TextOptions.Mode = TextProcessingMode.Update; options.TextOptions.SkipMode = TextSkipMode.KnownSymbolic; options.TextOptions.UnicodeSource = UnicodeSource.InstalledFont; ``` **Java:** ```java // Configure text OCR: update non-extractable text with correct Unicode options.getTextOptions().setMode(TextProcessingMode.UPDATE); options.getTextOptions().setSkipMode(EnumSet.of(TextSkipMode.KNOWN_SYMBOLIC)); options.getTextOptions().setUnicodeSource(EnumSet.of(UnicodeSource.INSTALLED_FONT)); ``` **Python:** ```python # Configure text OCR: update non-extractable text with correct Unicode options.text_options.mode = TextProcessingMode.UPDATE options.text_options.skip_mode = TextSkipMode.KNOWN_SYMBOLIC options.text_options.unicode_source = UnicodeSource.INSTALLED_FONT ``` **C:** ```c // Configure text OCR: update non-extractable text with correct Unicode pTextOptions = PdfToolsOcr_OcrOptions_GetTextOptions(pOptions); PdfToolsOcr_TextOptions_SetMode(pTextOptions, ePdfToolsOcr_TextProcessingMode_Update); PdfToolsOcr_TextOptions_SetSkipMode(pTextOptions, ePdfToolsOcr_TextSkipMode_KnownSymbolic); PdfToolsOcr_TextOptions_SetUnicodeSource(pTextOptions, ePdfToolsOcr_UnicodeSource_InstalledFont); ``` ### Page options Page options control page-level processing and accessibility tagging. - **`All`**: Process all non-empty pages. - **`IfNoText`**: Process only pages that have content but no text. - **`AddResults`**: Don't trigger OCR independently, but add page-level results when OCR is triggered by image or text processing. The `Tagging` property controls PDF tagging for accessibility: - **`Auto`**: Automatically add tagging for scanned or already-tagged documents. Recommended for most workflows. - **`Update`**: Always add tagging. A warning is emitted if tagging fails. - **`None`**: Don't add any tagging. **.NET:** ```csharp // Configure page OCR: process all pages and add tagging for accessibility options.PageOptions.Mode = PageProcessingMode.All; options.PageOptions.Tagging = TaggingMode.Auto; ``` **Java:** ```java // Configure page OCR: process all pages and add tagging for accessibility options.getPageOptions().setMode(PageProcessingMode.ALL); options.getPageOptions().setTagging(TaggingMode.AUTO); ``` **Python:** ```python # Configure page OCR: process all pages and add tagging for accessibility options.page_options.mode = PageProcessingMode.ALL options.page_options.tagging = TaggingMode.AUTO ``` **C:** ```c // Configure page OCR: process all pages and add tagging for accessibility pPageOptions = PdfToolsOcr_OcrOptions_GetPageOptions(pOptions); PdfToolsOcr_PageOptions_SetMode(pPageOptions, ePdfToolsOcr_PageProcessingMode_All); PdfToolsOcr_PageOptions_SetTagging(pPageOptions, ePdfToolsOcr_TaggingMode_Auto); ``` ### Resolution settings The `OcrOptions` object also controls the resolution for OCR processing. Each page's optimal OCR resolution is determined automatically. If the optimal resolution falls within the configured range, the default resolution is used. A warning is generated if a page's optimal resolution falls outside the range. - **`Dpi`**: Default resolution (default: 300). - **`MinDpi`**: Minimum allowed resolution (default: 200). - **`MaxDpi`**: Maximum allowed resolution (default: 400). ### Embedded files Set `ProcessEmbeddedFiles` to `true` on the `OcrOptions` object to recursively process PDF files embedded within the input document. By default, embedded files are copied as-is without OCR processing. ## Process the document Create a `Processor` instance and register a warning handler before calling `Process`. The processor applies the configured OCR options and writes the result to the output stream. Warnings provide diagnostic information about each page, such as images with resolution outside the configured range or tagging issues. Warnings are non-critical. The Pdftools SDK completes processing even when warnings occur. However, depending on your use case, you may need to treat certain warning categories as errors. | Category | Description | When to treat as error | |--|--|--| | `Ocr` | OCR-related issues such as resolution outside the optimal range | Rarely (usually informational) | | `Tagging` | Issues adding tagging or structural information | When producing accessible PDFs or preparing for PDF/A level A | | `Text` | Issues making text extractable | When text extraction is the primary goal | | `SignedDocument` | Processing removed existing digital signatures | When preserving signatures is important | :::important[Signed documents] Processing a signed PDF invalidates all existing digital signatures, which are removed during processing. The `SignedDocument` warning is generated when this occurs. **.NET:** ```csharp // Create the OCR processor and add a warning handler var processor = new Processor(); processor.Warning += (s, e) => { Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : ""); }; // Create stream for output file using var outStr = File.Create(outPath); // Process the document with OCR using var outDoc = processor.Process(inDoc, engine, outStr, options); ``` **Java:** ```java // Create the OCR processor and add a warning handler Processor processor = new Processor(); processor.addWarningListener(new Processor.WarningListener() { @Override public void warning(Processor.Warning event) { System.out.println(String.format("- %s: %s (%s%s)", event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " page " + event.getPageNo() : "")); } }); // Create stream for output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Process the document with OCR Document outDoc = processor.process(inDoc, engine, outStr, options, null); ``` **Python:** ```python def warning_handler(message: str, category, page_no: int, context: str): if page_no > 0: print(f"- {category.name}: {message} ({context} page {page_no})") else: print(f"- {category.name}: {message} ({context})") # Create the OCR processor and add a warning handler processor = Processor() processor.add_warning_handler(warning_handler) # Create stream for output file with io.FileIO(output_path, 'wb+') as output_stream: # Process the document with OCR processor.process(input_document, engine, output_stream, options) ``` **C:** ```c // Create the OCR processor and add a warning handler pProcessor = PdfToolsOcr_Processor_New(); PdfToolsOcr_Processor_AddWarningHandler(pProcessor, NULL, WarningHandler); // Create stream for output file pOutStream = _tfopen(szOutPath, _T("wb+")); TPdfToolsSys_StreamDescriptor outDesc; PdfToolsSysCreateFILEStreamDescriptor(&outDesc, pOutStream, 0); // Process the document with OCR pOutDoc = PdfToolsOcr_Processor_Process(pProcessor, pInDoc, pEngine, &outDesc, pOptions, NULL); ``` ### Handle warnings by category For workflows where certain warnings are critical, filter warnings by category. This example treats tagging and text warnings as errors: **.NET:** ```csharp processor.Warning += (s, e) => { if (e.Category == WarningCategory.Tagging || e.Category == WarningCategory.Text) throw new Exception($"Critical OCR warning: {e.Message}"); Console.WriteLine($"Warning: {e.Category}: {e.Message}"); }; ``` **Java:** ```java processor.addWarningListener(new Processor.WarningListener() { @Override public void warning(Processor.Warning event) { if (event.getCategory() == WarningCategory.TAGGING || event.getCategory() == WarningCategory.TEXT) throw new RuntimeException("Critical OCR warning: " + event.getMessage()); System.out.println(String.format("Warning: %s: %s", event.getCategory(), event.getMessage())); } }); ``` **Python:** ```python def warning_handler(message: str, category, page_no: int, context: str): if category in (WarningCategory.TAGGING, WarningCategory.TEXT): raise Exception(f"Critical OCR warning: {message}") print(f"Warning: {category.name}: {message}") ``` **C:** ```c void PDFTOOLS_CALL WarningHandler(void* pContext, const TCHAR* szMessage, TPdfToolsOcr_WarningCategory iCategory, int iPageNo, const TCHAR* szContext) { if (iCategory == ePdfToolsOcr_WarningCategory_Tagging || iCategory == ePdfToolsOcr_WarningCategory_Text) { _tprintf(_T("Critical OCR warning: %s\n"), szMessage); // Handle as error (e.g. set error flag) return; } _tprintf(_T("Warning: %d: %s\n"), iCategory, szMessage); } ``` ## Full example **.NET:** ```csharp // Create the OCR engine using var engine = Engine.Create(ocrEngineName); // Set the language(s) for OCR recognition (e.g. "German,English") engine.Languages = language; // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Configure OCR options var options = new OcrOptions(); // Configure image OCR: recognize text from scanned images options.ImageOptions.Mode = ImageProcessingMode.UpdateText; options.ImageOptions.RemoveOnlyInvisibleOcrText = true; options.ImageOptions.DeskewScan = true; options.ImageOptions.RotateScan = true; // Configure text OCR: update non-extractable text with correct Unicode options.TextOptions.Mode = TextProcessingMode.Update; options.TextOptions.SkipMode = TextSkipMode.KnownSymbolic; options.TextOptions.UnicodeSource = UnicodeSource.InstalledFont; // Configure page OCR: process all pages and add tagging for accessibility options.PageOptions.Mode = PageProcessingMode.All; options.PageOptions.Tagging = TaggingMode.Auto; // Create the OCR processor and add a warning handler var processor = new Processor(); processor.Warning += (s, e) => { Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " page " + e.PageNo : ""); }; // Create stream for output file using var outStr = File.Create(outPath); // Process the document with OCR using var outDoc = processor.Process(inDoc, engine, outStr, options); ``` **Java:** ```java // Create the OCR engine try (Engine engine = Engine.create(ocrEngineName)) { // Set the language(s) for OCR recognition (e.g. "German,English") engine.setLanguages(language); // Open input document try ( FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr)) { // Configure OCR options OcrOptions options = new OcrOptions(); // Configure image OCR: recognize text from scanned images options.getImageOptions().setMode(ImageProcessingMode.UPDATE_TEXT); options.getImageOptions().setRemoveOnlyInvisibleOcrText(true); options.getImageOptions().setDeskewScan(true); options.getImageOptions().setRotateScan(true); // Configure text OCR: update non-extractable text with correct Unicode options.getTextOptions().setMode(TextProcessingMode.UPDATE); options.getTextOptions().setSkipMode(EnumSet.of(TextSkipMode.KNOWN_SYMBOLIC)); options.getTextOptions().setUnicodeSource(EnumSet.of(UnicodeSource.INSTALLED_FONT)); // Configure page OCR: process all pages and add tagging for accessibility options.getPageOptions().setMode(PageProcessingMode.ALL); options.getPageOptions().setTagging(TaggingMode.AUTO); // Create the OCR processor and add a warning handler Processor processor = new Processor(); processor.addWarningListener(new Processor.WarningListener() { @Override public void warning(Processor.Warning event) { System.out.println(String.format("- %s: %s (%s%s)", event.getCategory(), event.getMessage(), event.getContext(), event.getPageNo() > 0 ? " page " + event.getPageNo() : "")); } }); // Create stream for output file try (FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW)) { // Process the document with OCR try (Document outDoc = processor.process(inDoc, engine, outStr, options, null)) { } } } } ``` **Python:** ```python def warning_handler(message: str, category, page_no: int, context: str): if page_no > 0: print(f"- {category.name}: {message} ({context} page {page_no})") else: print(f"- {category.name}: {message} ({context})") # Create the OCR engine with Engine.create(ocr_engine_name) as engine: # Set the language(s) for OCR recognition (e.g. "German,English") engine.languages = language # Open input document with io.FileIO(input_path, 'rb') as in_stream: with Document.open(in_stream) as input_document: # Configure OCR options options = OcrOptions() # Configure image OCR: recognize text from scanned images options.image_options.mode = ImageProcessingMode.UPDATE_TEXT options.image_options.remove_only_invisible_ocr_text = True options.image_options.deskew_scan = True options.image_options.rotate_scan = True # Configure text OCR: update non-extractable text with correct Unicode options.text_options.mode = TextProcessingMode.UPDATE options.text_options.skip_mode = TextSkipMode.KNOWN_SYMBOLIC options.text_options.unicode_source = UnicodeSource.INSTALLED_FONT # Configure page OCR: process all pages and add tagging for accessibility options.page_options.mode = PageProcessingMode.ALL options.page_options.tagging = TaggingMode.AUTO # Create the OCR processor and add a warning handler processor = Processor() processor.add_warning_handler(warning_handler) # Create stream for output file with io.FileIO(output_path, 'wb+') as output_stream: # Process the document with OCR processor.process(input_document, engine, output_stream, options) ``` **C:** ```c void PDFTOOLS_CALL WarningHandler(void* pContext, const TCHAR* szMessage, TPdfToolsOcr_WarningCategory iCategory, int iPageNo, const TCHAR* szContext) { if (iPageNo > 0) _tprintf(_T("- %d: %s (%s page %d)\n"), iCategory, szMessage, szContext, iPageNo); else _tprintf(_T("- %d: %s (%s)\n"), iCategory, szMessage, szContext); } // Create the OCR engine pEngine = PdfToolsOcr_Engine_Create(szOcrEngineName); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pEngine, _T("Failed to create OCR engine. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Set the language(s) for OCR recognition (e.g. "German,English") GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_Engine_SetLanguages(pEngine, szLanguage), _T("Failed to set OCR languages. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Open input document pInStream = _tfopen(szInPath, _T("rb")); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pInStream, _T("Failed to open the input file \"%s\" for reading.\n"), szInPath); TPdfToolsSys_StreamDescriptor inDesc; PdfToolsSysCreateFILEStreamDescriptor(&inDesc, pInStream, 0); pInDoc = PdfToolsPdf_Document_Open(&inDesc, _T("")); GOTO_CLEANUP_IF_NULL_PRINT_ERROR( pInDoc, _T("Failed to create a document from the input file \"%s\". %s (ErrorCode: 0x%08x).\n"), szInPath, szErrorBuff, PdfTools_GetLastError()); // Configure OCR options pOptions = PdfToolsOcr_OcrOptions_New(); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pOptions, _T("Failed to create OCR options. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Configure image OCR: recognize text from scanned images pImageOptions = PdfToolsOcr_OcrOptions_GetImageOptions(pOptions); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pImageOptions, _T("Failed to get image options. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR( PdfToolsOcr_ImageOptions_SetMode(pImageOptions, ePdfToolsOcr_ImageProcessingMode_UpdateText), _T("Failed to set image processing mode. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_ImageOptions_SetRemoveOnlyInvisibleOcrText(pImageOptions, TRUE), _T("Failed to set RemoveOnlyInvisibleOcrText. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_ImageOptions_SetDeskewScan(pImageOptions, TRUE), _T("Failed to set DeskewScan. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_ImageOptions_SetRotateScan(pImageOptions, TRUE), _T("Failed to set RotateScan. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Configure text OCR: update non-extractable text with correct Unicode pTextOptions = PdfToolsOcr_OcrOptions_GetTextOptions(pOptions); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pTextOptions, _T("Failed to get text options. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR( PdfToolsOcr_TextOptions_SetMode(pTextOptions, ePdfToolsOcr_TextProcessingMode_Update), _T("Failed to set text processing mode. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR( PdfToolsOcr_TextOptions_SetSkipMode(pTextOptions, ePdfToolsOcr_TextSkipMode_KnownSymbolic), _T("Failed to set text skip mode. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR( PdfToolsOcr_TextOptions_SetUnicodeSource(pTextOptions, ePdfToolsOcr_UnicodeSource_InstalledFont), _T("Failed to set unicode source. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Configure page OCR: process all pages and add tagging for accessibility pPageOptions = PdfToolsOcr_OcrOptions_GetPageOptions(pOptions); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pPageOptions, _T("Failed to get page options. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR( PdfToolsOcr_PageOptions_SetMode(pPageOptions, ePdfToolsOcr_PageProcessingMode_All), _T("Failed to set page processing mode. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_PageOptions_SetTagging(pPageOptions, ePdfToolsOcr_TaggingMode_Auto), _T("Failed to set tagging mode. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Create the OCR processor and add a warning handler pProcessor = PdfToolsOcr_Processor_New(); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pProcessor, _T("Failed to create OCR processor. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfToolsOcr_Processor_AddWarningHandler(pProcessor, NULL, WarningHandler), _T("Failed to add warning handler. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); // Create stream for output file pOutStream = _tfopen(szOutPath, _T("wb+")); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pOutStream, _T("Failed to create output file \"%s\" for writing.\n"), szOutPath); TPdfToolsSys_StreamDescriptor outDesc; PdfToolsSysCreateFILEStreamDescriptor(&outDesc, pOutStream, 0); // Process the document with OCR pOutDoc = PdfToolsOcr_Processor_Process(pProcessor, pInDoc, pEngine, &outDesc, pOptions, NULL); GOTO_CLEANUP_IF_NULL_PRINT_ERROR(pOutDoc, _T("The processing has failed. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, PdfTools_GetLastError()); ``` --- ## OCR best practices Performance and operational guidance for using the OCR module in production environments. ## Minimize OCR operations A page is sent to the OCR engine only when required by the configured modes. Set only the modes you need to avoid unnecessary processing: - To OCR scanned images only, set `ImageOptions.Mode` and leave other modes at `None`. - To fix non-extractable text only, set `TextOptions.Mode` and leave other modes at `None`. - To process entire pages, set `PageOptions.Mode`. This triggers OCR for all matching pages regardless of other modes. - `PageProcessingMode.AddResults` doesn't trigger OCR on its own. It only adds page-level results when OCR is already triggered by another mode. For details on each mode, refer to [Configure OCR options](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf#configure-ocr-options). ## Reuse the OCR engine Create one `Engine` instance and reuse it across multiple documents. Creating a new engine for each document adds overhead because the engine connection and configuration must be re-established each time. **.NET:** ```csharp // Create the engine once using var engine = Engine.Create("service@http://localhost:7982/"); engine.Languages = "German,English"; // Configure options once var options = new OcrOptions(); options.ImageOptions.Mode = ImageProcessingMode.UpdateText; // Create the processor once var processor = new Processor(); // Process multiple documents with the same engine foreach (var inputPath in inputFiles) { using var inStr = File.OpenRead(inputPath); using var inDoc = Document.Open(inStr); using var outStr = File.Create(GetOutputPath(inputPath)); using var outDoc = processor.Process(inDoc, engine, outStr, options); } ``` **Java:** ```java // Create the engine once try (Engine engine = Engine.create("service@http://localhost:7982/")) { engine.setLanguages("German,English"); // Configure options once OcrOptions options = new OcrOptions(); options.getImageOptions().setMode(ImageProcessingMode.UPDATE_TEXT); // Create the processor once Processor processor = new Processor(); // Process multiple documents with the same engine for (String inputPath : inputFiles) { try ( FileStream inStr = new FileStream(inputPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); FileStream outStr = new FileStream(getOutputPath(inputPath), FileStream.Mode.READ_WRITE_NEW)) { try (Document outDoc = processor.process(inDoc, engine, outStr, options, null)) { } } } } ``` **Python:** ```python # Create the engine once with Engine.create("service@http://localhost:7982/") as engine: engine.languages = "German,English" # Configure options once options = OcrOptions() options.image_options.mode = ImageProcessingMode.UPDATE_TEXT # Create the processor once processor = Processor() # Process multiple documents with the same engine for input_path in input_files: with io.FileIO(input_path, 'rb') as in_stream: with Document.open(in_stream) as in_doc: with io.FileIO(get_output_path(input_path), 'wb+') as out_stream: processor.process(in_doc, engine, out_stream, options) ``` **C:** ```c // Create the engine once pEngine = PdfToolsOcr_Engine_Create(_T("service@http://localhost:7982/")); PdfToolsOcr_Engine_SetLanguages(pEngine, _T("German,English")); // Configure options once pOptions = PdfToolsOcr_OcrOptions_New(); pImageOptions = PdfToolsOcr_OcrOptions_GetImageOptions(pOptions); PdfToolsOcr_ImageOptions_SetMode(pImageOptions, ePdfToolsOcr_ImageProcessingMode_UpdateText); // Create the processor once pProcessor = PdfToolsOcr_Processor_New(); // Process multiple documents with the same engine for (int i = 0; i < nFiles; i++) { FILE* pInStream = _tfopen(szInputPaths[i], _T("rb")); TPdfToolsSys_StreamDescriptor inDesc; PdfToolsSysCreateFILEStreamDescriptor(&inDesc, pInStream, 0); TPdfToolsPdf_Document* pInDoc = PdfToolsPdf_Document_Open(&inDesc, _T("")); FILE* pOutStream = _tfopen(szOutputPaths[i], _T("wb+")); TPdfToolsSys_StreamDescriptor outDesc; PdfToolsSysCreateFILEStreamDescriptor(&outDesc, pOutStream, 0); TPdfToolsPdf_Document* pOutDoc = PdfToolsOcr_Processor_Process( pProcessor, pInDoc, pEngine, &outDesc, pOptions, NULL); PdfToolsPdf_Document_Close(pOutDoc); fclose(pOutStream); PdfToolsPdf_Document_Close(pInDoc); fclose(pInStream); } ``` One `Engine` instance can only process one document at a time. ## Scale with the OCR Service The [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) processes multiple pages concurrently. Performance scales with: - The number of running OCR Service instances. - The number of parallel processes configured in each instance. For high-throughput workflows, deploy additional OCR Service instances and connect to them using multiple URLs (for example, `"service@http://host1:7982/;http://host2:7982/"`). ## Optimize engine parameters Use engine-specific parameters to improve performance: - Deactivate recognition features you don't need (for example, barcode detection when you only need text). - Use a predefined profile optimized for your use case (for example, `"PredefinedProfile=Default"`). - Consult the OCR engine manual for engine-specific tuning options. ## Thread safety The Pdftools SDK OCR module is thread-safe with one rule: **an object may only be accessed by one thread at a time.** - You can process multiple documents concurrently, provided each thread uses its own `Engine` and `Document` instances. - Some OCR engines must be disposed in the same thread where they were created. - The OCR Service is recommended for concurrent processing because it handles thread safety internally. ## Resource management Close all OCR objects after use. The `Engine`, input `Document`, and output `Document` returned by `Processor.Process` are all disposable resources. - **.NET**: Use `using` statements. - **Java**: Use try-with-resources. - **Python**: Use `with` context managers. - **C**: Call `PdfToolsOcr_Engine_Close` and `PdfToolsPdf_Document_Close`. ### Disposal ordering The output `Document` returned by `Processor.Process` must be disposed **before** the output stream is closed. If you close the stream first, the document cannot flush its remaining data and the output file may be incomplete or corrupt. The following examples show the key lines from the [full OCR example](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf#full-example): **.NET:** Declare the output document *after* the output stream so that `using` disposes them in the correct (reverse) order. ```csharp // Create stream for output file using var outStr = File.Create(outPath); // Process the document with OCR using var outDoc = processor.Process(inDoc, engine, outStr, options); // outDoc is disposed first, then outStr — correct order ``` **Java:** Declare both resources in a single try-with-resources block. Java closes them in reverse declaration order. ```java // Create stream for output file and process the document with OCR try (FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); Document outDoc = processor.process(inDoc, engine, outStr, options, null)) { } // outDoc is closed first, then outStr — correct order ``` **Python:** Close the output document before closing the output stream. Nest `with` statements so the document context exits first. ```python # Create stream for output file with io.FileIO(output_path, 'wb+') as output_stream: # Process the document with OCR with processor.process(input_document, engine, output_stream, options) as output_document: pass # output_document is closed first, then output_stream — correct order ``` **C:** Close the output document before closing the output stream. ```c // Process the document with OCR pOutDoc = PdfToolsOcr_Processor_Process(pProcessor, pInDoc, pEngine, &outDesc, pOptions, NULL); // Close in correct order: document first, then stream PdfToolsPdf_Document_Close(pOutDoc); fclose(pOutStream); ``` ### Engine instance limits Some OCR engines only allow a single instance per process. Creating a second `Engine` of the same type fails in that case. This is another reason to create one engine and reuse it across documents. For complete examples showing proper resource management in each language, refer to [OCR a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf#full-example). --- ## OCR a PDF with the Shell Tool Run OCR on a PDF directly from the command line with the [Pdftools SDK Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool). The Shell Tool sends pages to an OCR engine and writes a new PDF with an invisible, selectable text layer while preserving the visual appearance of the document. The Shell Tool exposes the same OCR module as the SDK. For an overview of how the OCR module processes a document and the three processing dimensions (image OCR, text OCR, page OCR), refer to [OCR with the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/). :::info[Pdftools OCR Service required] The OCR command requires a running [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) instance. For installation details, review [Set up Pdftools OCR Service with Pdftools SDK](https://www.pdf-tools.com/docs/ocr-service/getting-started/windows/set-up-with-sdk/). :::note[Before you begin] - [Download and unpack the Pdftools SDK Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool#download). - [Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license). Pass your license key with `-lk "YOUR_LICENSE_KEY"` to remove the watermark from the output. Include the less-than (`<`) and greater-than (`>`) signs. - Start a Pdftools OCR Service instance. The default endpoint is `http://localhost:7982/`. ## Command syntax ```bash pdf ocr -ocr service[@[;...]] [options] ``` The minimal invocation is: ```bash pdf in.pdf ocr -ocr service -oim updateText out.pdf ``` This sends `in.pdf` to a local OCR Service at `http://localhost:7982/` and writes a searchable copy to `out.pdf`. To connect to a different host, append the URL after `service@`: ```bash pdf in.pdf ocr -ocr service@http://ocr.example.com:7982/ -oim updateText out.pdf ``` To distribute load across multiple OCR Service instances, separate URLs with a semicolon: ```bash pdf in.pdf ocr -ocr "service@http://host1:7982/;http://host2:7982/" -oim updateText out.pdf ``` ## Engine options The Pdftools SDK Shell Tool supports a single OCR engine, `service`, which delegates recognition to a [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) instance. | Option | Description | |--------|-------------| | `-ocr ` | Select an OCR engine. Supported: `service[@[;...]]`. Without a URL, the Shell Tool connects to `http://localhost:7982/`. | | `-ocl ` | Set OCR recognition languages as a comma-separated string, for example `-ocl "German,English"`. | | `-ocp ` | Pass engine-specific recognition parameters as semicolon-separated key-value pairs, for example `-ocp "PredefinedProfile=Default"` or `-ocp "Profile=/path/to/custom-profile.ini"`. | ## Image OCR options Image OCR recognizes text in scanned images and adds an invisible text layer. For mode descriptions and use-case guidance, refer to [Image OCR](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/#image-ocr). Mode values are case-insensitive (`UpdateText` and `updateText` are equivalent). The tables on this page use the same UpperCamelCase form as the SDK enums. | Option | Description | |--------|-------------| | `-oim ` | Image OCR mode: `None` (default), `UpdateText`, `ReplaceText`, `RemoveText`, `IfNoText`. | | `-oca` | Rotate the scan according to the rotation detected by the OCR engine. | | `-occs` | Deskew the scan according to the skew angle detected by the OCR engine. | | `-otr3` | When `-oim` is `ReplaceText` or `RemoveText`, remove only invisible OCR text (text rendering mode 3) and preserve other text. | ## Text OCR options Text OCR fixes non-extractable text in born-digital PDFs by determining the correct Unicode values for characters whose fonts lack proper mappings. For mode descriptions, refer to [Text OCR](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/#text-ocr). | Option | Description | |--------|-------------| | `-otm ` | Text OCR mode: `None` (default), `Update`, `Replace`. | | `-ots ` | Skip text by font category. Values: `None` (default), `KnownSymbolic`, `PrivateUseArea`. Combine flags with commas, for example `-ots "KnownSymbolic,PrivateUseArea"`. | | `-otu ` | Additional Unicode mapping sources. Values: `None` (default), `InstalledFont`, `KnownSymbolicPua`, `FallbackAllPua`. Combine flags with commas, for example `-otu "InstalledFont,KnownSymbolicPua"`. | ## Page OCR options Page OCR processes entire pages and adds OCR results as page text. It can also add PDF tagging for accessibility compliance. For mode descriptions, refer to [Page OCR](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/#page-ocr). | Option | Description | |--------|-------------| | `-opm ` | Page OCR mode: `None` (default), `All`, `IfNoText`, `AddResults`. | | `-tm ` | Tagging mode: `Auto` (default), `None`, `Update`. Adds PDF structure tags for accessibility. | ## General options | Option | Description | |--------|-------------| | `-ocd ` | OCR resolution in DPI. `` is the default, `` the minimum, `` the maximum. The values must satisfy `d1 <= d <= d2`. | | `-pef` | Process embedded PDF files recursively. | ## Examples ### Make a scanned document searchable Apply OCR to scanned images with default options. The OCR engine connects to `http://localhost:7982/` and uses English by default: ```bash pdf in.pdf ocr -ocr service -oim updateText -ocl English out.pdf ``` ### Combine image, text, and page OCR Run all three processing dimensions in a single pass to recognize scanned images, fix non-extractable text, and add accessibility tagging: ```bash pdf in.pdf ocr \ -ocr service \ -ocl "German,English" \ -oim updateText \ -otm update \ -opm ifNoText \ -tm Auto \ out.pdf ``` ### Adjust OCR resolution Set the resolution range used to render pages for the OCR engine. Pages are rendered at the default DPI when possible and clamped between the minimum and maximum: ```bash pdf in.pdf ocr -ocr service -oim updateText -ocd 300 200 600 out.pdf ``` ### Process embedded files Apply OCR to embedded PDF files alongside the main document: ```bash pdf in.pdf ocr -ocr service -oim updateText -pef out.pdf ``` ### Chain OCR with other commands The Shell Tool [chains commands](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool#chain-commands) with `:`. For example, OCR a scanned document and then convert it to PDF/A-2b in a single invocation: ```bash pdf in.pdf ocr -ocr service -oim updateText : convert -pdfa pdfa-2b out.pdf ``` ## Related topics - [OCR with the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/): overview, processing dimensions, and use cases. - [OCR a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf): equivalent walkthrough using the SDK in .NET, Java, Python, and C. - [OCR best practices](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-best-practices): performance, thread safety, and resource management guidance. - [Pdftools SDK Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool): installation, licensing, and command chaining. --- ## Compress and optimize PDF documents The Pdftools SDK lets you optimize PDF documents to suit specific target needs such as electronic document exchange, archiving, or printing. Many processes produce PDF documents that may not be optimized for their specific target application. For example, the file size may deteriorate download times, or the same font embedded multiple times may impede printing. With the Pdftools SDK, you can easily configure the process through [optimization profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimization-profiles) and determine specific output through various configuration options. The Pdftools SDK reads an input document and writes the corresponding output document. Depending on the configured optimization options, various parts of the PDF are processed as required. The SDK is capable of removing redundant or alternative information, sub­setting and merging font programs, downsampling images, and intelligently choosing optimal compression algorithms. Depending on the desired output, you can [compress and optimize images](#compress-and-optimize-images), [fonts](#optimize-fonts), [page content and document structure](#compress-and-optimize-content-and-structure). You can set the minimum PDF version of the output file. You can get a log report on the PDF file, listing fonts and images and their respective properties, and extract the number of pages. ## Compress and optimize images Images can increase file size significantly. The Pdftools SDK optimizes image objects, letting you configure image compression by image type, choose the compression algorithm and compression quality, set color management options such as color profiles and color channels, and convert or remove image objects partially or completely. **Compression process** - Separately configure compression of bitonal, indexed, and continuous (that is, color and grayscale) images - Define threshold in dots per inch (DPI) for triggering image downsampling - Define target image resolution in DPI for image downsampling - Automatically select best compression type for each image - Configure enforcement of configured compression types **Image object handling** - Perform mixed raster content (MRC) optimization for images - Convert soft masks to image masks if applicable - Remove invisible parts of images - Remove images entirely and substitute by empty XObjects **Color management** - Choose color management engine - Reduce the number of color channels used for images, image masks, and soft masks, if applicable - Convert colors to CMYK, RGB, or grayscale ## Optimize fonts If your PDF documents do not need to be edited, then there is no need to embed a font as a binary stream in the PDF document. You can subset font programs, removing all unused glyphs that are not needed to reproduce the document. You can determine when to remove standard fonts and when to merge fonts and font programs. - Subset font programs to contain only the used glyphs - Merge compatible font programs and fonts - Compress Type 1 fonts (convert to CFF) - Remove font programs ## Compress and optimize content and structure Unnecessary objects increase file size without reason. With the Pdftools SDK, you can remove these unused, redundant and unwanted objects to reduce file size and speed up rendering. - Remove unused resources - Optimize page content automatically - Flatten or remove page annotations and form fields - Remove unnecessary data: - Redundant objects - Embedded standard fonts (such as Courier, Arial, and Times) - Embedded, non-symbolic fonts - Unnecessary file information - Article threads - Alternative images - Metadata - Page-piece information - Output intent - Signature appearances - Document structure tree, including markup - Miniature page preview images - Spider (web capture) information :::tip[Get started] Learn **[how to optimize a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimize-a-pdf)** for a specific use. --- ## Optimization profiles An optimization profile contains predetermined configuration settings that help you optimize a PDF document for a specific use. The Pdftools SDK offers four optimization profiles: - **[Web](#web-optimization-profile)**: Compress the file without affecting viewing quality on digital devices - Removes redundant and unnecessary data for electronic document exchange - Downsamples, clips, and intelligently compresses images - Merges and subsets fonts - Converts colors to RGB - **[Archive](#archive-optimization-profile)**: Prepare a document for archiving in PDF/A format - Removes redundant and unnecessary data for archiving - Intelligently compresses images - Merges and subsets fonts - **[Print](#print-optimization-profile)**: Compress the file without affecting print quality - Removes redundant and unnecessary data for printing - Downsamples, clips, and intelligently compresses images - Merges and subsets fonts - Converts colors to CMYK - **[Minimal file size](#minimal-file-size-optimization-profile)**: Remove redundant data and reduce image resolution to achieve a minimal viable file size - Downsamples images - Converts Type1 fonts to Type1C - Removes metadata and output intents - **[Mixed Raster Content (MRC)](#mixed-raster-content-optimization-profile)**: Apply Mixed Raster Content (MRC) optimization intended for compressing scanned PDF files containing large amounts of text. The MRC can include: - Splitting documents into foreground, background, and mask layers - Heavily downsampling and compressing foreground and background layers - Lossless compression of mask layers - Merging and subsetting fonts ## Web optimization profile All documents related to the web should be kept small in file size. As a consequence, they take less storage on the web server and can be transferred quicker, resulting in shorter download times. To reduce the file size as much as possible, all information that is not required for displaying the document without a visual loss can be removed. This may include: - Downsampling images - Clipping images to their visible parts - Applying compressions algorithms with high compression ratios - Collapsing redundant objects - Removing unused resources - Removing irrelevant information such as article threads, metadata, alternate images, and document structure information - Merging and sub-setting embedded font programs With the Web optimization profile, images above 210 DPI are down-sampled and recompressed to 150 DPI. This leads to smaller output files. When an image is recompressed, the `Balanced` strategy is used; however, this can be overridden through `ImageRecompressionOptions`. Depending on the PDF documents to be optimized, font programs of embedded standard fonts can even be removed. Additionally, PDF documents can be linearized. A PDF file is prepared so that pages can be accessed randomly via a PDF viewer web browser plugin, meaning selected pages can be displayed before the whole file is downloaded. For this to work, the PDF viewer web browser plugin has to support correct interpretation of linearized PDF. Documents that are intended to be displayed on a display should be saved in RGB (red green blue) color space. RGB is the native form for any light-emitting device, such as computer monitor or television. An RGB image uses three channels, and therefore takes up less space than a CMYK (cyan magenta yellow black) image, which uses four channels. With the Web optimization profile, all colors are converted to RGB. **important: With the **Web** optimization profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.** ## Print optimization profile For printing applications, the file size is not the highest priority. It is more important to have a document that prints predictably. This means that correct fonts should be used, colors should look as expected, and images should be high in resolution. For that reason, data from the original document that is used for a well-defined reproduction should not be removed or altered. Embedded fonts should not be removed, images should not be downsampled, with exceptions. For many printing applications, it may be beneficial to convert images to the CMYK color space because this is primarily used in systems that reflect light (such as printed paper). With the **Print** optimization profile, all colors are converted to CMYK for optimal output on printing devices. In certain documents, the same font is embedded multiple times. For example, if a PDF-producing software embeds the same font for each created page, then large multi-page documents may contain many copies of a font program. Also, a document can contain a complete font program of which only very few glyphs are used for display. In such situations, merging and sub-setting font programs can lead to faster printing. Embedded Type1 (PostScript) fonts are converted to Type1C (Compact Font Format), which further reduces the file size. There are still further ways to decrease the file size: - Clipping images to their visible parts - Compressing uncompressed images, for example, with a lossless compression type - Collapsing redundant objects - Removing unused resources - Removing irrelevant information for printing such as thumbnails, article threads, and document structure information With this profile, spider (web capture) information is removed. The resolution of images is not modified. When an image is recompressed, the `PreserveQuality` strategy is used; this can be overridden through the property `ImageRecompressionOptions`. **important: With the **Print** profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.** ## Archive optimization profile For archiving, the priority is to preserve PDF/A conformance, maintaining document fidelity and reproducibility over time. Only minimal document modification is performed. This may include: - Removing alternative images - Removing thumbnails - Collapsing redundant objects - Removing unused resources The resolution and color space of images must remain untouched. When an image is recompressed, the `PreserveQuality` strategy is used to ensure the image keeps as high a quality as possible compared to the original; however, it can be overridden through the property `ImageRecompressionOptions`. All content objects such as annotations, form fields, and links are copied with the **Archiving** profile. Article threads, metadata, piece-info dictionaries, and the structure tree are not removed. Signature appearances are flattened. **important: For PDF/A conforming input files, the PDF/A conformance is preserved if possible. For other files, the PDF version is updated to PDF 1.7 or higher.** ## Minimal file size optimization profile In most cases, the focus in PDF optimization to decrease the file size. This can be achieved by: - Compressing images with an appropriate compression algorithm for lower image quality. - Collapsing redundant objects. - Removing unused resources. - Removing irrelevant information for printing such as thumbnails, article threads, document structure information, and piece-info dictionaries. - Remove output intents. With the `MinimalFileSize` conversion profile, the output file size is further reduced by converting Embedded Type1 (PostScript) fonts to Type1C (Compact Font Format). Metadata and spider (web capture) information are removed. Output intents provide a means for matching the color characteristics of PDF page content with those of a target output device or production environment in which the document is printed. Output intents are removed with the **minimal file size** optimization profile. Images above 182 DPI are downsampled and recompressed to 130 DPI. This leads to smaller output files. When an image is recompressed, the `Balanced` strategy is used; this can be overridden through the property `ImageRecompressionOptions`. ## Mixed raster content optimization profile PDF files with scanned content can have a very large file size due to the high resolution of the images stored in scanned PDF files. Minimizing the image size while maintaining text readability is important for workflows involving scanned text documents. The Mixed Raster Content (MRC) algorithm minimizes the image size while maintaining text readability. The MRC divides scanned documents into foreground, background, and mask layers, storing the textual information in the mask layer using a lossless compression type. The MRC heavily down-samples and compresses foreground and background layers. The file size is further reduced by removing redundant objects, optimizing resources, merging and subsetting embedded fonts. **important: With the **Minimal file size** profile, the output PDF version is updated to PDF 1.7 or higher and PDF/A conformance is removed.** --- ## Compress and optimize a PDF document The Pdftools SDK lets you compress and optimize a PDF document for a specific purpose. Depending on the specified purpose, different operations are performed on the PDF document, such as reducing image resolution or removing unnecessary objects. You can encrypt the output PDF as part of the optimization process. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/OptimizerSimple)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/OptimizerSimple)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/OptimizerSimple)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/OptimizerSimple)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/OptimizerSimple)**. The Pdftools SDK currently supports five [optimization profiles](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimization-profiles) that are intended for the following purposes: - **Archive:** Prepare a document for archiving in PDF/A format, reducing the file size prior to converting to PDF/A. - **Minimal file size:** Remove redundant data and reduce image resolution to achieve a minimal viable file size. - **Print:** Compress the file, but ensure that the print quality of the document is not affected. - **Web:** Similar to the Print profile, but ensure that the viewing quality of the document is not affected when viewing on digital devices (for example, in a web browser). - **Mixed raster content:** Apply Mixed Raster Content (MRC) optimization intended for compressing scanned documents that contain large amounts of text. **Steps to optimize a document**: 1. [Read the input document](#read-the-input-document) 2. [Create an Optimizer object](#create-an-optimizer-object) 3. [Set an optimization profile](#set-an-optimization-profile) 4. [Run the OptimizeDocument method](#run-the-optimizedocument-method) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input document First you need to read the PDF document you want to optimize. To do this, load the input document from the file system into a read-only input `Document`. This `Document` can then later be passed to the `Optimizer`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); ``` ## Create an Optimizer object You start the document optimization process by creating an `Optimizer` object. The `Optimizer` object takes an input PDF document and optimizes the content for a specific purpose. It then outputs the result to a document object that can be persisted to a file or used as an input for further processing. **.NET:** ```csharp // Create the Optimizer object. Optimizer optimizer = new Optimizer(); ``` **Java:** ```java // Create the Optimizer object. Optimizer optimizer = new Optimizer(); ``` ## Set an optimization profile The `Profile` object controls the behavior of the `Optimizer` object during the optimization process. The [profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimization-profiles) can be set to one of four subclasses that are used for different purposes: `Archive`, `MinimalFileSize`, `Print`, and `Web`. This example uses the `Web` profile. **.NET:** ```csharp // Create a profile that controls the Optimizer output behavior. // The Web profile is used to optimize documents for electronic document exchange. var profile = new Profiles.Web(); // Archive, MinimalFileSize, Print, Web // Optionally, the profile's parameters can be changed according to the // requirements of your optimization process ``` **Java:** ```java // Create the profile that defines the optimization parameters. // The Web profile is used to optimize documents for electronic document exchange. Web profile = new Web(); // Archive, MinimalFileSize, Print, Web // Optionally, the profile's parameters can be changed according to the // requirements of your optimization process ``` ## Run the OptimizeDocument method After creating the `Optimizer` and `Profile` objects, the final step is to call the `OptimizeDocument` method. The document produced by this method has the optimizations applied to it that are defined by the optimization profile. If the output document cannot be created, a detailed error message is generated. **.NET:** ```csharp // Create the output stream. using var outStr = File.Create(outPath); // Optimize the document and save it to a file. using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Optimize the document Document outDoc = optimizer.optimizeDocument(inDoc, outStr, profile); ``` **tip: During the optimization process, the output file may be encrypted and may be assigned permissions.** For more information on how PDF documents are encrypted, see [Encryption in PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/pdf-encryption). ## Full example **.NET:** ```csharp // Open the PDF document to optimize using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create the Optimizer object. Optimizer optimizer = new Optimizer(); // Create a profile that controls the Optimizer output behavior. // The Web profile is used to optimize documents for electronic document exchange. var profile = new Profiles.Web(); // Create the output stream. using var outStr = File.Create(outPath); // Optimize the document and save it to a file. using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile); ``` **Java:** ```java // Create the Optimizer object. Optimizer optimizer = new Optimizer(); // Create the profile that defines the optimization parameters. // The Web profile is used to optimize documents for electronic document exchange. Web profile = new Web(); // Optionally, the profile's parameters can be changed according to the // requirements of your optimization process. try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Optimize the document Document outDoc = optimizer.optimizeDocument(inDoc, outStr, profile)) { } ``` --- ## Sign and secure PDF documents Digital signatures play a crucial role in verifying the authenticity and integrity of electronic documents or messages. Applying a digital signature to a PDF document allows the reader to verify that the document has not been tampered with or altered in any way, and that it was produced by the person who claims to have produced it. PDF documents can be secured from unauthorized access by applying encryption, and by restricting access to specific users through passwords. Applying encryption to a PDF document ensures that the contents of the document can only be read by the audience for whom the document is intended. With the Pdftools SDK, you can create, manage, and validate all types of digital signatures and encryption in PDF documents. Learn more about: - [Signing PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/) - [PDF security](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/) --- ## Secure PDF documents PDF documents can be protected from unauthorized access, restricting access to specific users with passwords and the use of encryption. However, any PDF application that processes or displays a PDF document must read and decrypt the contents of the pages. Technically, it cannot display an encrypted text or image without first decrypting it. Therefore, a PDF application program has full access to any PDF document it can decrypt and display. :::note[Note about encryption and PDF/A] Encryption is not allowed by the PDF/A ISO standards. For that reason, encryption options must not be used when processing PDF/A documents. Otherwise, PDF/A conformance is removed from the output document. For more information, see [PDF/A](https://www.pdf-tools.com/docs/knowledge/pdf-a/). The encryption process applies encryption to all streams (such as images) and strings, but not to other items in the PDF document. This means the structure of the PDF document is accessible, but the content of its pages is encrypted. The Pdftools SDK uses security handlers for **[encryption in PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/pdf-encryption)**. :::tip[Get started] Learn **[how to encrypt a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/encrypt-a-pdf)** with the Pdftools SDK. --- ## Encrypt and decrypt a PDF document The Pdftools SDK provides methods to open and save encrypted PDF documents. The [PDF encryption process](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/pdf-encryption) applies encryption to all streams (such as images) and text, but not to other items in the PDF document. This means the structure of the PDF document is accessible, but the content of its pages is encrypted. ## Open an encrypted PDF document :::tip[Quick start with a code sample] Get the full encryption sample on GitHub: - **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Encrypt)** - **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Encrypt)** - **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Encrypt)** - **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Encrypt)** - **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Encrypt)** Get the full decryption sample on GitHub: - **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Decrypt)** - **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Decrypt)** - **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Decrypt)** - **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Decrypt)** - **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Decrypt)** To open an encrypted PDF document, a password must be provided. Up to two passwords can be specified for a document: an 'Owner' password and a 'User' password. Permissions for a document depends on the type of password provided. See [Permissions and passwords in PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/pdf-encryption#permissions-and-passwords-in-pdf-documents). :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. In the Pdftools SDK, the password is provided as an optional parameter to the static `Document.Open` method. **.NET:** ```csharp // Open an encrypted input document // The password parameter is optional, and only required to open an encrypted PDF document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr, password); ``` **Java:** ```java // Open an encrypted input document // The password parameter is optional, and only required to open an encrypted PDF document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr, password) ``` If the PDF document is encrypted and the `password` parameter is not provided or is not valid, the `Document.Open` method fails with a `PasswordException`. ## Save an encrypted PDF document :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Encrypt)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Encrypt)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Encrypt)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Encrypt)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Encrypt)**. With the Pdftools SDK, you can open and read encrypted PDF files using the standard security handler. You can encrypt output PDF documents, adding an owner password, a user password, or both. This example shows how encryption is applied to the output document during the PDF optimization process. You can also apply encryption during other processes where `OutputOptions` are used, such as signing. **.NET:** ```csharp // Create output stream using var outStr = File.Create(outPath); // Create output options and specify encryption parameters // In this example, a 'User' is only granted permission to fill forms and print the document var outOpt = new OutputOptions(); var outEnc = new Encryption(strUserPassword, strOwnerPassword, (Permission.FillForms | Permission.Print)); outOpt.Encryption = outEnc; // Optimize the input PDF document and save it to a file, applying the specified output encryption using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile, outOpt); ``` **Java:** ```java // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create output options and specify encryption parameters // In this example, a 'User' is only granted permission to fill forms and print the document OutputOptions outOpt = new OutputOptions(); // Set a user password that is required to open the document. // Note that this removes PDF/A conformance of input files (see warning category WarningCategory.PDF_A_REMOVED) outOpt.setEncryption(new Encryption(strUserPassword, strOwnerPassword, EnumSet.of(Permission.FILL_FORMS, Permission.PRINT))); // Optimize the input PDF document and save it to a file, applying the specified output encryption Document outDoc = new Optimizer().optimizeDocument(inDoc, outStr, profile, outOpt); ``` ## Remove encryption from an encrypted PDF document Removing encryption from an encrypted document is as simple as the process for encrypting the document. After you have opened the encrypted document, the document can be processed in the same way as for encryption, but setting the `Encryption` to `null`. **.NET:** ```csharp // Create output options and remove encryption by setting it to null var outOpt = new OutputOptions(); outOpt.Encryption = null; // Allow removal of signatures. Otherwise the Encryption property is ignored for signed input documents. outOpt.RemoveSignatures = SignatureRemoval.Signed; ``` **Java:** ```java // Create output options and remove encryption by setting it to null OutputOptions outOpt = new OutputOptions(); outOpt.setEncryption(null); // Allow removal of signatures. Otherwise the Encryption property is ignored for signed input documents. outOpt.setRemoveSignatures(SignatureRemoval.SIGNED); ``` --- ## Encryption in PDF documents When encryption is used in PDF, a security handler must be selected. The Pdftools SDK always uses the standard security handler that, according to the PDF Specification, must be supported by any software that can process encrypted PDF documents. **tip: For more detailed information about PDF encryption in general, consult **[PDF Reference, chapter 3.5](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.7old.pdf#3.5-encryption)**.** ## Permissions and passwords in PDF documents The standard security handler allows access permissions for the document. Up to two passwords can be specified for a document: - [Owner password](#owner-password) - [User password](#user-password) ### Owner password An owner password is also referred to as the author's password. This password grants full access to the document. It lets the document be opened and read, and also lets the document's security settings (access permission and passwords) to be changed. ### User password A user password protects the document against unauthorized opening and reading. If a PDF document is protected by a user password, either the user or owner password must be provided to open and read the document. If a document has a user password, it must have an owner password as well. If no owner password is defined, the owner password is the same as the user password. The following table shows the four possible combinations of passwords and how an application processing such a PDF document behaves. | User password | Owner password | Behavior | | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | None | None | Everyone can read. Everyone can change security settings. (No encryption) | | None | Set | Everyone can read. The user password is an empty string. Owner password required to change security settings. | | Set | None | User password required to read. The owner password is equal to the user password. User password required to change security settings. | | Set | Set | User or owner password required to read. Owner password required to change security settings. | ### Permission flags The operations granted in a PDF document are controlled by permission flags. To set permission flags, the PDF document must be encrypted and have an owner password. The owner password is required to initially set or later change the permission flags. These access permission flags determine operations such as: - Modify the content of the document - Copy or extract text and graphics from the document - Add or modify text annotations and interactive form fields - Print the document (low or high quality) - Fill in forms and digitally sign the document - Assemble the document (insert, rotate, and delete pages) ## Read a PDF document A PDF document that is not encrypted or protected with an owner password only can be read and decrypted by the Pdftools SDK `Open` function without providing a password. A PDF document that is protected by a user password can only be opened if either the user or the owner password is provided as parameter in the `Open` function. Technically, it does not matter later on which of the two passwords was provided, because both grant full access to the document. However, it is up to the application programmer to distinguish between input documents that are password protected or not. ## Encrypt a PDF document If either of the passwords or permission flags is set, the document is encrypted. If only a user password is set, but no owner password and no permission flags, the owner password is equal to the user password and all permissions are granted. To encrypt a document and protect it against any manipulations other than printing, the document must have an owner password and the print permission flag set. **note: To learn how to encrypt and decrypt a document with the Pdftools SDK, see [Encrypt a PDF](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/encrypt-a-pdf).** ## Security and PDF encryption PDF application programs such as all products of the Pdftools family or Adobe Acrobat can open and decrypt PDF documents that have an owner password but no user password, without knowing that password. Otherwise, it couldn't display the document. The application at that point has full access to the document. However, this does not imply the user of this application is given the same access rights. The user should only be given the access permissions defined by the permission flags and the password provided. Any PDF application that behaves different from that can allow for changing the security settings or completely removing encryption from the document as long as the original document does not have a user password. The user password protects the document, so that it only can be opened if the user or owner password is known. No PDF application program can open a user-password protected PDF document without providing the password. However, the security of such a document strongly depends on the password itself. Like in most password-related situations, insecure passwords can easily be found programmatically. For example, a brute force attempt testing all passwords that either exist as word in a dictionary or have less than six characters only takes minutes. --- ## Sign PDF documents With the Pdftools SDK, you can create, manage, and validate different types of [digital signatures](#digital-signature-types) in a PDF document. You can choose from a variety of local and online [cryptographic providers](#supported-cryptographic-providers) to support your legal and regulatory requirements. ## Digital signature types A digital signature is a technique used to verify the authenticity and integrity of an electronic document or message. It is created by applying a cryptographic algorithm to the document or message, using a private key. The resulting digital signature can then be [verified](#validate-signatures) using the corresponding public key, which is made available to anyone who wants to verify the signature. Digital signatures are used to ensure that a document or message has not been tampered with or altered in any way, and that it was sent by the person who claims to have sent it. The Pdftools SDK supports three types of digital signature: - **[Document approval signatures](#document-approval-signatures)** - **[Document certification signatures](#document-certification-signatures)** - **[Time-stamp signatures](#time-stamp-signatures)** **tip: For theoretical information about digital signatures, review [Digital signature basics](https://www.pdf-tools.com/docs/knowledge/digital-signature-basics/).** ### Document approval signatures Document approval signatures add a digital signature to a document as part of a workflow, such as approving and signing contracts. This type of digital signature records the identity of the signer, and confirms that the content of the document has not changed after the signature was applied. There can be multiple document approval signatures associated with a document. For example, if multiple parties sign a contract, each document approval signature has a unique digital signature. The signatures are applied successively to create a signature chain. :::tip[Get started] Learn how to **[sign a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document)** with a document approval signature. ### Document certification signatures Document certification signatures are also known as Modification Detection and Prevention (MDP) signatures. This type of signature records the identity of the document author. It allows users to make specific changes to the document, while retaining the validity of the signature. For example, the author may allow a document's form fields to be filled by the user, while retaining the validity of the signature. If changes occur to the document that have not been permitted by the author, the signature is invalidated. There can be at most one document certification signature in a document, and it must be added before any other signatures are added to the document. A typical workflow involving a document certification signature would be: 1. A document certification signature is applied to a template document, allowing form filling. 2. A user fills the form fields with their personal information. 3. A [document approval signature](#document-approval-signatures) is applied to the document, preventing any further changes from being made. The following settings can be used for document certification signatures: - **No changes**: No changes to the document are permitted; any change to the document invalidates the signature. - **Form filling**: The user may fill forms, instantiate page templates, and sign; any other change invalidates the signature. - **Annotate**: The user may make the same changes as for form filling, as well as create, delete, and modify annotations; any other change invalidates the signature. :::tip[Get started] Learn how to **[certify a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-certify)** with a document certification signature. ### Time-stamp signatures Time-stamp signatures provide evidence that a document existed at a specific time, and that the content of the document has not changed since that time. Often, time-stamp signatures are used to "re-sign" a previously signed document to confirm that it remains unchanged. The time-stamp is provided by an independent, [trusted time-stamp authority](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/timestamp-authority). :::tip[Get started] Learn how to **[apply a digital time-stamp to a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-timestamp)** with a time-stamp signature. ## Supported cryptographic providers The cryptographic provider manages certificates and the associated private keys, and implements cryptographic algorithms. The Pdftools SDK supports a range of [cryptographic providers](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/cryptographic-providers). ## Embed long-term validation information To ensure a signature can be validated over time, [long-term validation information](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) should be embedded in the document during the signing process. If you embed LTV information in a document, the signature in the document remains valid even after the certificate expires or if the certificate is later revoked. **note: Long-term validation (LTV) is not always possible. It must be supported by the certificate authority and the cryptographic provider.** ## Sign PDF/A documents Many types of documents that require digital signatures also require archiving. For example, by the recipient of a signed contract. For archiving, PDF/A conformance is typically required to ensure that the file is not corrupt and that its visual appearance is well defined and reproducible. However, during the [conversion process from PDF to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa), any signatures are removed from the file before it is converted to PDF/A for archival. Therefore, files that require archiving should be [archived to PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) before any digital signatures are applied. ## Validate signatures The Pdftools SDK lets you validate document approval and document certification signatures and timestamps according to a specific criteria (constraints). Signatures can be validated using sources such as certificates, Online Certificate Status Protocol (OCSP) results, and Certificate Revocation List (CRL) results. These sources can be embedded in the PDF file, stored on the local machine, or downloaded from the issuer. The validation process can return a list of all signatures and their corresponding details and even trigger specific business logic using events. :::tip[Get started] Learn how to **[validate signatures](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-validate)** in a document. ## Create a signature visual appearance The Pdftools SDK allows for adding a [visual appearance](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/signature-appearance) for a signature. This applies for [document approval signatures](#document-approval-signatures), [document certification signatures](#document-certification-signatures), [time-stamp signatures](#time-stamp-signatures) and signing existing unsigned signatures. --- ## Set up digital signing for Pdftools SDK Depending on the type of digital signature you want to add to documents using the Pdftools SDK, you may need to: - Configure the connection to a remote service using [HTTPS connection](#configure-https-connections) - Store certificates in a [local directory](#store-local-certificates) recognized by the SDK - Set up the SDK to route requests via a [proxy server](#use-a-proxy-server) ## Configure HTTPS connections When the Pdftools SDK connects to a remote service using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified by the `HttpClientHandler` class. If the verification process fails, the connection to the server is aborted. The verification process requires a trust store; otherwise, verification always fails. The system's default trust store is used. Additional trusted certificates may be added using the `AddTrustedCertificate` method of the `HttpClientHandler` class. When an SSL/TLS connection requires a client certificate (for example, when connecting to an online signing service), the `SetClientCertificate` and `SetClientCertificateAndKey` methods of the `HttpClientHandler` class are used to set the client certificate and its private key. The default trust store is configured in the following locations: **Windows:** The Windows certificate store for _Trusted Root Certification Authorities_ is used. You can install the root certificate of a private CA manually on a computer by using the `CertMgr` tool. The certificate store is only available if the user profile has been loaded. **Linux:** The certificates available in `CAfile` and `CApath` are trusted: ### CAfile The file can contain a concatenated sequence of CA certificates in PEM format. The SDK searches for the file at the following locations: - The file of your local OpenSSL installation (if `libssl.so` is found), or - the environment variable `SSL_CERT_FILE`, or - the default location `/etc/ssl/cert.pem` ### CApath A directory containing CA certificates in PEM format. The files are looked up by the CA subject name hash value. For example, `9d66eef0.0`. The SDK searches for the directory at the following locations: - The directory of your local OpenSSL installation (if `libssl.so` is found), or - the environment variable `SSL_CERT_DIR`, or - the default location `/etc/ssl/certs/` **macOS:** The trusted certificates from the macOS keychain are used. You can install the root certificate of a private CA manually by dragging the certificate file to the `Keychain Access` app. **note: If it is not possible to verify the server certificate, you can disable verification by setting the `SslVerifyServerCertificate` property of the `HttpClientHandler` to `false`.** However, this approach is strongly discouraged in any production environment. ## Store local certificates When [signing PDF documents](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document), additional certificates may be required. For example, you may need additional certificates when the `OutputOptions` class is configured to add all certificates of the signing certificate's trust chain to the output document security store (DSS) to enable [long-term signature validation (LTV)](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation). If the certificate provider allows certificates to be downloaded, the Pdftools SDK downloads the required certificates and stores them in a local `Certificates` directory. You may also manually add certificates to the `Certificates` directory. The Pdftools SDK stores and searches for local certificates, in either PEM (.pem, ASCII text) or DER (.cer, binary) format, in the following locations: **Windows:** ``` %LOCALAPPDATA%\PDF Tools AG\Certificates %ProgramData%\PDF Tools AG\Certificates ``` **Linux:** ``` ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates /usr/share/pdf-tools/Certificates ``` **macOS:** ``` ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates ``` ## Use a proxy server Some of the features of the Pdftools SDK require access to a remote service. These features include: - Connecting to a [time-stamp authority (TSA)](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/timestamp-authority) to retrieve a time-stamp - Connecting to an [online signing service](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/cryptographic-providers#online-signing-services) to access document signing functions - Connecting to a certificate authority to retrieve certificates and revocation information If your software runs in a secured environment, it may be necessary or preferable to configure a proxy server to route requests from the Pdftools SDK to these remote services. To configure a proxy, assign the `PdfTools.Sdk` class a `Proxy` server URI that the SDK will use for all HTTP and HTTPS communications with remote services. ### Proxy server URI The default value for the `Proxy` server URI property is `null`, meaning that no proxy is used. Otherwise, the property’s value must be a URI with the following elements: http[s]://[USER[:PASSWORD]@]HOST[:PORT] Where: - `http`/`https`: Protocol for connection to proxy. - `USER:PASSWORD` (optional): Credentials for connection to proxy (basic authorization). - `HOST`: Hostname of proxy. - `PORT`: Port for connection to proxy Example: `http://user:password@myproxy:8080` ### SSL/TLS connections to online signing services For SSL/TLS connections (for example, to the [GlobalSign](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-globalsign) or [Swisscom](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-swisscom) signature services), the proxy must allow `HTTP CONNECT` requests to the remote server. ### Connections to time-stamp authorities If you want to sign documents using time-stamp certificates, the following MIME types must be supported: - `application/timestamp-query` - `application/timestamp-reply` ### Embedded long-term validation information If you plan to embed [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information in the digital signatures, then the following MIME types must be supported: - `application/ocsp-request` - `application/ocsp-response` --- ## Cryptographic providers(Sign) For digital signatures to be applied to a document, a cryptographic provider must be configured. The cryptographic provider manages certificates and the associated private keys, and implements cryptographic algorithms. The cryptographic provider used impacts the legal effect of your digital signatures, and often depends on your local legal and regulatory requirements. If you are unsure of these requirements, contact your local Certificate Authority (CA) for guidance. The Pdftools SDK supports a range of cryptographic providers: - [Built-in cryptographic provider](#built-in-cryptographic-provider) - [PKCS#11 provider](#pkcs11-provider) - [Online signing services](#online-signing-services), such as GlobalSign and Swisscom ## Built-in cryptographic provider The built-in cryptographic provider requires no cryptographic hardware or external service, except for an optional connection to an external time-stamp service. Signing certificates with private keys can be loaded directly from a PFX (PKCS#12) soft certificate stored as a local file, using the Pdftools SDK. Additional certificates can be stored in a local [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates). These additional certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) format. :::tip[Get started] Learn [how to sign a PDF document using the built-in cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin). ## PKCS#11 provider The PKCS#11 provider creates a session to a cryptographic device such as an HSM or USB token to perform cryptographic operations. It requires a driver module (middleware). More information on the driver required can be found in the documentation for your cryptographic device. The [PKCS#11 Tech Note](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf) provides detailed information about configuring a PKCS#11 device to work with the Pdftools SDK. :::tip[Get started] Learn [how to sign a PDF document using a PKCS#11 device](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-pkcs11). ## Online signing services Online signing services are cloud-based cryptographic providers that enable their customers to sign documents and provide them with time-stamps. ### GlobalSign Digital Signing Service This provider implements the methods of the [GlobalSign Digital Signing Service](https://www.globalsign.com/en/digital-signatures). A GlobalSign account is required. :::tip[Get started] Learn [how to sign a PDF document using the GlobalSign Digital Signing Service](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-globalsign). ### Swisscom Signing Service This provider implements the methods of the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/). A Swisscom account is required. :::tip[Get started] Learn [how to sign a PDF document using the Swisscom Signing Service](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-swisscom). --- ## Embed long-term validation (LTV) information The Pdftools SDK can be configured to embed long-term validation (LTV) information into a document during the [document signing process](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). When the Pdftools SDK is configured to embed LTV information, it attempts to embed revocation information such as **online certificate status response** ([OCSP - RFC2560](https://datatracker.ietf.org/doc/html/rfc2560)) and **certificate revocation lists** ([CRL - RFC3280](https://datatracker.ietf.org/doc/html/rfc3280)). Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. Embedding revocation information is optional, but recommended when applying advanced (AES) or qualified electronic signatures (QES). Revocation information is embedded for the signing certificate and all certificates of its trust chain. Therefore, both OCSP responses and CRLs may be present in the same message. However, embedding revocation information increases the file size (usually around 20 kB), and requires an external request to a validation service, which may delay the signing process. :::note[LTV in time-stamp signatures] Long-term validation (LTV) information cannot be embedded directly for [time-stamp signatures](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-timestamp). Instead, after the time-stamp signature has been applied, the `Process` method of the `Signer` class must be invoked again to embed LTV information for each of the certificates in the document. ## HTTPS connections When retrieving certificate revocation information from a remote server using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified using the system's default trust store (CA certificate store). You need to [set up the HTTPS connection](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#configure-https-connections) to communicate with the Pdftools SDK. ## Proxy server In a secured environment, the firewall must be configured to allow connection to the remote server. If you [use a proxy server](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#use-a-proxy-server), the following MIME types must be supported: - `application/ocsp-request` - `application/ocsp-response` --- ## Built-in cryptographic provider The `BuiltIn` cryptographic provider enables access to the cryptographic functions of the local operating system. For example, to [sign a document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). No cryptographic hardware or external service is required, except for the optional `TimestampUrl` used when applying a [time-stamp](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-timestamp). You can load signing certificates with private keys directly from a PFX (PKCS#12) file using the `CreateSignatureFromCertificate` method. Additional certificates (for example, issuer certificates) are stored in the [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates). These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form. In this example, a `BuiltIn` cryptographic provider is used to apply a document approval signature to a PDF document. The PFX certificate is read from a local file. Information required for long-term signature validation (LTV) is embedded in the output PDF. **Steps to sign a document**: 1. [Initialize the cryptographic provider](#initialize-the-cryptographic-provider). 2. [Read the PFX or P12 certificate](#read-the-pfx-or-p12-certificate). 3. [(Optional) Add long-term validation information](#add-long-term-validation-information) 4. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Initialize the cryptographic provider When using the `BuiltIn` cryptographic provider, you start the digital signing process by instantiating the `Provider` object. The `Provider` object exposes the methods of the local operating system's cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms. **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); ``` **Java:** ```java // Create a session to the built-in cryptographic provider Provider session = new Provider(); ``` ## Read the PFX or P12 certificate PFX certificate files can be loaded directly into the `BuiltIn` cryptographic provider from the file system. The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature. **.NET:** ```csharp // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); ``` **Java:** ```java // Create signature configuration from PFX (or P12) file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY); SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); ``` **tip: If you are using a Java `KeyStore` that has already been loaded, for example `ks`, you can use a `MemoryStream` to create the `SignatureConfiguration`.** ```java // Create an OutputStream to write the KeyStore to (into memory) ByteArrayOutputStream os = new ByteArrayOutputStream(); // Write the KeyStore to the OutputStream ks.store(os, password.toCharArray()); // Put the OutputStream bytes into a MemoryStream Stream certStr = new MemoryStream(os.toByteArray()); // Create signature configuration from that MemoryStream SignatureConfiguration signature = session.createSignatureFromCertificate(certStr, password); ``` The `KeyStore` must be of type `PKCS12`. For more information on the `KeyStore`, refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html). ## Add long-term validation information As an optional step, [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. **.NET:** ```csharp // Embed validation information to enable the long-term validation (LTV) of the signature signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; ``` **Java:** ```java // Embed validation information to enable the long term validation (LTV) of the signature (default) signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); ``` ## Open and sign the document After instantiating the `Provider` and preparing the signature configuration, you are ready to apply the digital signature to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // (optionally) Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optionally) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr); ``` ## Full example **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create stream for output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java try ( // Create a session to the built-in cryptographic provider Provider session = new Provider(); // Open certificate file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY)) { // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long term validation (LTV) of the signature (default) signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); // Create the Signer object Signer signer = new Signer(); // (optionally) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr)) { } } ``` :::important[Signing PDF/A documents] During the [conversion process from PDF to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa), any signatures are removed from the file before it is converted to PDF/A for archiving. Therefore, files that require archiving should be [archived to PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) before any digital signatures are applied. --- ## GlobalSign cryptographic provider The `GlobalSignDss` cryptographic provider enables access to the [GlobalSign Digital Signing Service](https://www.globalsign.com/en/digital-signatures) (GlobalSign DSS). The service can then be used to perform cryptographic functions such as [sign a document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). This provider requires a GlobalSign DSS account. Accounts with static and dynamic identities are supported. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/GlobalSignDssSign)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/GlobalSignDssSign)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/GlobalSignDssSign)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/GlobalSignDssSign)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/GlobalSignDssSign)**. The GlobalSign DSS provides signing certificates and basic cryptographic (PKCS#1) signatures. Additional certificates such as issuer certificates are stored in the [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates). These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form. In this example, the `GlobalSignDss` cryptographic provider is used to apply a document approval signature to a PDF document. The signing certificate is loaded from the GlobalSign DSS. An account that supports dynamic identities is used. The signing certificate is identified by passing the common name of the certificate. Information required for long-term signature validation (LTV) is embedded in the output PDF. **Steps to sign a document**: 1. [Configure the HTTP client handler](#configure-the-http-client-handler). 2. [Connect to GlobalSign DSS](#connect-to-globalsign-dss). 3. [Create the document signature](#create-the-document-signature). 4. [(Optional) Add long-term validation information](#add-long-term-validation-information). 5. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Configure the HTTP client handler When using the `GlobalSignDss` cryptographic provider, you need to configure the `HttpClientHandler` with the SSL client certificate, private key, and password from your GlobalSign DSS account. **.NET:** ```csharp // Configure the SSL client certificate to connect to the GlobalSign DSS service var httpClientHandler = new HttpClientHandler(); using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer")) using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key")) httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password); ``` **Java:** ```java // Configure the SSL client certificate to connect to the service HttpClientHandler httpClientHandler = new HttpClientHandler(); try ( FileStream sslClientCert = new FileStream("C:/path/to/clientcert.cer", FileStream.Mode.READ_ONLY); FileStream sslClientKey = new FileStream("C:/path/to/privateKey.key", FileStream.Mode.READ_ONLY)) { httpClientHandler.setClientCertificateAndKey(sslClientCert, sslClientKey, password); } ``` ## Connect to GlobalSign DSS The next step is to open a `Session` to the GlobalSign DSS by logging in with the API key and secret from your GlobalSign DSS account. The `Session` object provides access to the certificates and private keys stored by GlobalSign. In this example, the default URI for the GlobalSign DSS is used. ### Advice on using the service Whenever you create a new GlobalSign `Session`, a login is performed. In this session, signatures can be created using different identities, that is, signing certificates, which are created as they are needed. Both signing sessions and signing certificates expire after 10 minutes. There are rate limits for both creating new identities and for signing operations. If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing. Due to the short-­lived nature of the signing certificates, it is important to embed revocation information immediately. For example, by using `AddValidationInformation` or `EmbedRevocationInfo`. Furthermore, it is highly recommended to embed a timestamp to prove that the signature was created during the certificate’s validity period. **.NET:** ```csharp // Connect to the GlobalSign Digital Signing Service using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler); ``` **Java:** ```java Session session = new Session(new URI("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler); ``` ## Create the document signature In this step, the `Session` object is used to create a signature configuration for a GlobalSign DSS account that supports dynamic identities. The signing certificate is identified by passing the common name of the certificate. The signature configuration may be used to sign one or more documents. **tip: If multiple documents must be signed at once, you should re-use the same session (and hence its signing certificates) for signing.** **.NET:** ```csharp // Create a signing certificate for an account with a dynamic identity // This can be re-used to sign multiple documents var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } }); var signature = session.CreateSignatureForDynamicIdentity(identity); ``` **Java:** ```java // Create a signing certificate for an account with a dynamic identity // This can be re-used to sign multiple documents SignatureConfiguration signature = session.createSignatureForDynamicIdentity(String.format("{ \"subject_dn\" : { \"common_name\" : \"%s\" } }", commonName)); ``` ## Add long-term validation information As an optional step, [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. **.NET:** ```csharp // Embed validation information to enable the long-term validation (LTV) of the signature signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; ``` **Java:** ```java // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setValidationInformation(ValidationInformation.EMBED_IN_DOCUMENT); ``` ## Open and sign the document After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr); ``` ## Full example **.NET:** ```csharp // Configure the SSL client certificate to connect to the GlobalSign DSS service var httpClientHandler = new HttpClientHandler(); using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.cer")) using (var sslClientKey = File.OpenRead(@"C:\path\to\privateKey.key")) httpClientHandler.SetClientCertificateAndKey(sslClientCert, sslClientKey, password); // Connect to the GlobalSign Digital Signing Service using var session = new GlobalSignDss.Session(new Uri("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler); // Create a signing certificate for an account with a dynamic identity var identity = JsonSerializer.Serialize(new { subject_dn = new { common_name = commonName } }); var signature = session.CreateSignatureForDynamicIdentity(identity); // Embed validation information to enable the long-term validation (LTV) of the signature signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Configure the SSL client certificate to connect to the service HttpClientHandler httpClientHandler = new HttpClientHandler(); try ( FileStream sslClientCert = new FileStream("C:/path/to/clientcert.cer", FileStream.Mode.READ_ONLY); FileStream sslClientKey = new FileStream("C:/path/to/privateKey.key", FileStream.Mode.READ_ONLY)) { httpClientHandler.setClientCertificateAndKey(sslClientCert, sslClientKey, "***insert password***"); } // Connect to the GlobalSign Digital Signing Service try (Session session = new Session(new URI("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler)) { // Create a signing certificate for an account with a dynamic identity // This can be re-used to sign multiple documents SignatureConfiguration signature = session.createSignatureForDynamicIdentity(String.format("{ \"subject_dn\" : { \"common_name\" : \"%s\" } }", commonName)); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setValidationInformation(ValidationInformation.EMBED_IN_DOCUMENT); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr)) { } } ``` --- ## PKCS#11 cryptographic provider The `Pkcs11` cryptographic provider enables access to a cryptographic device using a PKCS#11 driver module. The cryptographic device can then be used to perform cryptographic functions such as [sign a document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). This provider requires a PKCS#11 driver module (middleware) to establish a session to a cryptographic device of a particular type. For example, a HSM, Cloud KMS, or USB token. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Pkcs11Sign)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Pkcs11Sign)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Pkcs11Sign)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/Pkcs11Sign)**. More information on the driver required can be found in the documentation for your cryptographic device. The [PKCS#11 Tech Note](https://www.pdf-tools.com/public/downloads/manuals/TechNotePKCS11.pdf) provides detailed information about configuring a PKCS#11 device to work with the Pdftools SDK. Signing certificates can be loaded from the cryptographic device. The certificate may be identified by using the certificate name, key ID or label. Signing certificates can also be added using the `AddCertificate` method. Additional certificates, for example, issuer certificates, are stored in the [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates). These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form. In this example, the `Pkcs11` cryptographic provider is used to apply a document approval signature to a PDF document. The signing certificate is loaded from the PKCS#11 device by passing a certificate name. **Steps to sign a document**: 1. [Load the PKCS#11 driver module](#load-the-pkcs11-driver-module). 2. [Log in to the PKCS#11 device](#log-in-to-the-pkcs11-device). 3. [Create the document signature](#create-the-document-signature). 4. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Load the PKCS#11 driver module When using the `Pkcs11` cryptographic provider, you start the digital signing process by loading the PKCS#11 driver module. The PKCS#11 driver module is used to connect to the cryptographic device, exposing the cryptographic functions of the device. **.NET:** ```csharp // Load the PKCS#11 driver module (middleware) // The module can only be loaded once in the application. using var module = Pkcs11.Module.Load(pkcs11Library); ``` **Java:** ```java // Load the PKCS#11 driver module (middleware) // The module can only be loaded once in the application. Module module = Module.load(pkcs11Library); ``` ## Log in to the PKCS#11 device The next step is to open a `Session` by logging into the cryptographic device using the driver module and a password. The `Session` object provides access to the certificates and private keys stored on the device. **.NET:** ```csharp // Create a session to the cryptographic device and log in // with the password (pin) using var session = module.Devices.GetSingle().CreateSession(password); ``` **Java:** ```java // Create a session to the cryptographic device and log in // with the password (PIN) Session session = module.getDevices().getSingle().createSession(password); ``` ## Create the document signature In this step, the `Session` object is used to create a signature configuration using a certificate stored on the device. The signature configuration may be used to sign one or more documents. In this example, a signing certificate is selected from the PKCS#11 device by passing a certificate name. **.NET:** ```csharp // Create the signature configuration // This can be re-used to sign multiple documents var signature = session.CreateSignatureFromName(certificate); ``` **Java:** ```java // Create the signature configuration // This can be re-used to sign multiple documents var signature = session.createSignatureFromName(certificate); ``` ## Open and sign the document After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr); ``` ## Full example **.NET:** ```csharp // Load the PKCS#11 driver module (middleware) // The module can only be loaded once in the application. using var module = Pkcs11.Module.Load(pkcs11Library); // Create a session to the cryptographic device and log in // with the password (pin) using var session = module.Devices.GetSingle().CreateSession(password); // Create the signature configuration // This can be re-used to sign multiple documents var signature = session.CreateSignatureFromName(certificate); // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java try ( // Load the PKCS#11 driver module (middleware) // The module can only be loaded once in the application. Module module = Module.load(pkcs11Library); // Create a session to the cryptographic device and log in // with the password (pin) Session session = module.getDevices().getSingle().createSession(password)) { // Create the signature configuration // This can be re-used to sign multiple documents SignatureConfiguration signature = session.createSignatureFromName(certificate); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr)) { } } ``` --- ## Swisscom cryptographic provider The `SwisscomSigSrv` cryptographic provider enables access to the [Swisscom Signing Service](https://trustservices.swisscom.com/en/signing-service/). The service can then be used to perform cryptographic functions such as [sign a document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). This provider requires a Swisscom Signing Service account. Accounts with static and on-demand identities are supported. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/SwisscomSigSrvSign)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/SwisscomSigSrvSign)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/SwisscomSigSrvSign)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/SwisscomSigSrvSign)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/SwisscomSigSrvSign)**. The Swisscom Signing Service provides signing certificates using CMS (PKCS#7) signatures. Additional certificates (for example, issuer certificates) are stored in the [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates). These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The [Certificates directory](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#store-local-certificates) may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form. In this example, the `SwisscomSigSrv` cryptographic provider is used to apply a document approval signature to a PDF document. The signing certificate is loaded from the Swisscom Signing Service using a static identity string provided by Swisscom. Information required for long-term signature validation (LTV) is embedded in the output PDF. **Steps to sign a document**: 1. [Configure the HTTP client handler](#configure-the-http-client-handler). 2. [Connect to Swisscom Signing Service](#connect-to-swisscom-signing-service). 3. [Create the document signature](#create-the-document-signature). 4. [(Optional) Add long-term validation information](#add-long-term-validation-information). 5. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Configure the HTTP client handler When using the `SwisscomSigSrv` cryptographic provider, you need to configure the `HttpClientHandler` with the SSL client certificate and password from your Swisscom account. **.NET:** ```csharp // Configure the SSL client certificate to connect to the Swisscom Signing Service var httpClientHandler = new HttpClientHandler(); using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.p12")) httpClientHandler.SetClientCertificate(sslClientCert, password); ``` **Java:** ```java // Configure the SSL client certificate to connect to the service HttpClientHandler httpClientHandler = new HttpClientHandler(); try (FileStream sslClientCert = new FileStream("C:/path/to/clientcert.p12", FileStream.Mode.READ_ONLY)) { httpClientHandler.setClientCertificate(sslClientCert, password); } ``` ## Connect to Swisscom Signing Service The next step is to open a `Session` to the Swisscom Signing Service. The `Session` object provides access to the certificates and private keys stored by Swisscom. In this example, the default URI for the Swisscom Signing Service is used. **.NET:** ```csharp // Connect to the Swisscom Signing Service using var session = new SwisscomSigSrv.Session(new Uri("https://ais.swisscom.com"), httpClientHandler); ``` **Java:** ```java Session session = new Session(new URI("https://ais.swisscom.com"), httpClientHandler); ``` ## Create the document signature In this step, the `Session` object is used to create a signature configuration for a Swisscom Signing Service account using a static identity string provided by Swisscom. With a static identity, the common name is used for the signature appearance and for the signature description stored in the PDF document. The signature configuration may be used to sign one or more documents. **tip: To sign with Mobile ID, you use the `CreateSignatureForDynamicIdentity` method and pass `StepUp` authorization parameters.** **.NET:** ```csharp // Create a signing certificate for a static identity var signature = session.CreateSignatureForStaticIdentity(identity, commonName); ``` **Java:** ```java // Create a signing certificate for a static identity // This can be re-used to sign multiple documents SignatureConfiguration signature = session.createSignatureForStaticIdentity(identity, commonName); ``` ## Add long-term validation information As an optional step, [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. **.NET:** ```csharp // Embed validation information to enable the long term validation (LTV) of the signature (default) signature.EmbedValidationInformation = true; ``` **Java:** ```java // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setEmbedValidationInformation(true); ``` ## Open and sign the document After opening the `Session` and creating the signature configuration, you are ready to apply the digital signature to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr); ``` ## Full example **.NET:** ```csharp // Configure the SSL client certificate to connect to the Swisscom Signing Service var httpClientHandler = new HttpClientHandler(); using (var sslClientCert = File.OpenRead(@"C:\path\to\clientcert.p12")) httpClientHandler.SetClientCertificate(sslClientCert, password); // Connect to the Swisscom Signing Service using var session = new SwisscomSigSrv.Session(new Uri("https://ais.swisscom.com"), httpClientHandler); // Create a signing certificate for a static identity var signature = session.CreateSignatureForStaticIdentity(identity, commonName); // Embed validation information to enable the long term validation (LTV) of the signature (default) signature.EmbedValidationInformation = true; // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Configure the SSL client certificate to connect to the service HttpClientHandler httpClientHandler = new HttpClientHandler(); try (FileStream sslClientCert = new FileStream("C:/path/to/clientcert.p12", FileStream.Mode.READ_ONLY)) { httpClientHandler.setClientCertificate(sslClientCert, password); } // Connect to the Swisscom Signing Service try (Session session = new Session(new URI("https://ais.swisscom.com"), httpClientHandler)) { // Create a signing certificate for a static identity // This can be re-used to sign multiple documents SignatureConfiguration signature = session.createSignatureForStaticIdentity(identity, commonName); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setEmbedValidationInformation(true); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr)) { } } ``` --- ## Certify a PDF document The Pdftools SDK lets you apply a document certification signature, also known as a Modification Detection and Prevention (MDP) signature, to a PDF document. This type of signature records the identity of the document author. It also allows users to make specific changes to the document, such as filling form fields, without invalidating the signature. There can be at most one document certification signature in a document, and it must be added before any other signatures are added to the document. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/BuiltInCertify)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/BuiltInCertify)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/BuiltInCertify)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/BuiltInCertify)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/BuiltInCertify)**. In this example, the [Built-in cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin) is used to digitally certify a PDF document. The permissions allow a user to fill form fields. Any other changes to the document cause the signature to be rejected. **note: Any of the [cryptographic providers supported by the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/cryptographic-providers) can be used to apply a document certification signature.** **Steps to certify a document**: 1. [Initialize the cryptographic provider](#initialize-the-cryptographic-provider). 2. [Read the PFX or P12 certificate](#read-the-pfx-or-p12-certificate). 3. [(Optional) Add long-term validation information](#add-long-term-validation-information) 4. [(Optional) Add user modification permissions](#add-user-modification-permissions) 5. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Initialize the cryptographic provider When using the [Built-in cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin), you start the digital signing process by instantiating the `Provider` object. The `Provider` object exposes the methods of the cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms. **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); ``` **Java:** ```java // Create a session to the built-in cryptographic provider Provider session = new Provider(); ``` ## Read the PFX or P12 certificate Using the Built-in cryptographic provider, PFX certificate files can be loaded directly into the cryptographic provider from the file system. The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature. **.NET:** ```csharp // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); ``` **Java:** ```java // Create signature configuration from PFX (or P12) file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY); SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); ``` ## Add long-term validation information As an optional step, [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. **.NET:** ```csharp // Embed validation information to enable the long-term validation (LTV) of the signature signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; ``` **Java:** ```java // Embed validation information to enable the long-term validation (LTV) of the signature signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); ``` ## Add user modification permissions As an optional step, the author may permit users to make specific modifications to the document without the signature being revoked. In this example, the user is permitted to fill form fields. **.NET:** ```csharp // Assign Form Filling user permissions to the document var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling); ``` **Java:** ```java // Assign form filling user permissions to the document MdpPermissionOptions permissions = new MdpPermissionOptions(MdpPermissions.FORM_FILLING); ``` ## Open and sign the document After instantiating the `Provider` and preparing the signature configuration, you are ready to digitally certify a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital certification. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Certify the output document using var outDoc = signer.Certify(inDoc, signature, outStr, permissions); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.certify(inDoc, signature, outStr, permissions); ``` ## Full example **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new PdfTools.Crypto.Providers.BuiltIn.Provider(); // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; // Assign Form Filling user permissions to the document var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling); // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create stream for output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Certify the output document using var outDoc = signer.Certify(inDoc, signature, outStr, permissions); ``` **Java:** ```java try ( // Create a session to the built-in cryptographic provider Provider session = new Provider(); // Open certificate file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY)) { // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); // Assign form filling user permissions to the document MdpPermissionOptions permissions = new MdpPermissionOptions(MdpPermissions.FORM_FILLING); // Create the Signer object Signer signer = new Signer(); // (optional) create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Certify the output document Document outDoc = signer.certify(inDoc, signature, outStr, permissions)) { } } ``` :::info[Signature visual appearance] You can also apply a visual appearance to the signatures. For more information, see [Create a signature visual appearance](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/signature-appearance) page. :::note[Signing PDF/A documents] During the [conversion process from PDF to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa), any signatures are removed from the file before it is converted to PDF/A for archiving. Therefore, files that require archiving should be [archived to PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) before any digital signatures are applied. --- ## Sign a PDF document The Pdftools SDK lets you apply a document approval signature to a PDF document. This type of signature records the identity of the signer, and confirms that the content of the document has not changed after the signature is applied. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/BuiltInSign)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/BuiltInSign)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/BuiltInSign)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/BuiltInSign)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/BuiltInSign)**. In this example, the [Built-in cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin) is used to apply a document approval signature to a PDF document. The PFX certificate is read from a local file. Information required for long-term signature validation (LTV) is embedded in the output PDF. **note: Any of the [cryptographic providers supported by the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/cryptographic-providers) can be used to apply a document approval signature.** **Steps to sign a document**: 1. [Initialize the cryptographic provider](#initialize-the-cryptographic-provider). 2. [Read the PFX or P12 certificate](#read-the-pfx-or-p12-certificate). 3. [(Optional) Add long-term validation information](#add-long-term-validation-information) 4. [Open and sign the document](#open-and-sign-the-document). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Initialize the cryptographic provider When using the [Built-in cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin), you start the digital signing process by instantiating the `Provider` object. The `Provider` object exposes the methods of the cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms. **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); ``` **Java:** ```java // Create a session to the built-in cryptographic provider Provider session = new Provider(); ``` ## Read the PFX or P12 certificate Using the Built-in cryptographic provider, PFX certificate files can be loaded directly into the cryptographic provider from the file system. The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature. **.NET:** ```csharp // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); ``` **Java:** ```java // Create signature configuration from PFX (or P12) file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY); SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); ``` ## Add long-term validation information As an optional step, [long-term validation](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/long-term-validation) information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing. **.NET:** ```csharp // Embed validation information to enable the long-term validation (LTV) of the signature signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; ``` **Java:** ```java // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); ``` ## Open and sign the document After instantiating the `Provider` and preparing the signature configuration, you are ready to apply the digital signature to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital document signature. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr); ``` ## Full example **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); var signature = session.CreateSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument; // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create stream for output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Sign the output document using var outDoc = signer.Sign(inDoc, signature, outStr); ``` **Java:** ```java try ( // Create a session to the built-in cryptographic provider Provider session = new Provider(); // Open certificate file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY)) { // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); // Embed validation information to enable the long-term validation (LTV) of the signature (default) signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT); // Create the Signer object Signer signer = new Signer(); // (optional) create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = signer.sign(inDoc, signature, outStr)) { } } ``` :::important[Signing PDF/A documents] During the [conversion process from PDF to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa), any signatures are removed from the file before it is converted to PDF/A for archiving. Therefore, files that require archiving should be [archived to PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) before any digital signatures are applied. --- ## Add a document time-stamp The Pdftools SDK lets you apply a time-stamp to a PDF document. This type of digital signature provides evidence that a document existed at a specific time, and that the content of the document has not changed since that time. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/BuiltInAddTimestamp)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/BuiltInAddTimestamp)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/BuiltInAddTimestamp)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/BuiltInAddTimestamp)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/BuiltInAddTimestamp)**. The time-stamp is provided by a [time-stamp authority](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/timestamp-authority) (TSA) that is configured in the cryptographic provider. In this example, the [Built-In cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin) is used to apply a time-stamp to a PDF document. A third-party time-stamp authority is configured in the cryptographic provider. **Steps to apply a digital time-stamp**: 1. [Initialize the cryptographic provider](#initialize-the-cryptographic-provider). 2. [Connect to the time-stamp authority](#connect-to-the-time-stamp-authority). 3. [Add the document time-stamp](#add-the-document-time-stamp). --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Initialize the cryptographic provider When using the [Built-In cryptographic provider](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin), you start the document time-stamp process by instantiating the `Provider` object. The `Provider` object exposes the methods of the cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms. **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); ``` **Java:** ```java // Create a session to the built-in cryptographic provider Provider session = new Provider(); ``` ## Connect to the time-stamp authority For the [Built-In](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin) and [PKCS#11](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-pkcs11) cryptographic providers, a third-party time-stamp authority must be configured. To do this, you pass [the URL of the time-stamp authority](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/timestamp-authority#time-stamp-authority-uri) to the cryptographic provider and call the `CreateTimestamp` method. **.NET:** ```csharp // Create time-stamp configuration session.TimestampUrl = timeStampUrl; var timestamp = session.CreateTimestamp(); ``` **Java:** ```java // Create time-stamp configuration session.setTimestampUrl(timeStampUrl); TimestampConfiguration timestamp = session.createTimestamp(); ``` ## Add the document time-stamp After instantiating the `Provider` and preparing the time-stamp configuration, you are ready to apply the digital time-stamp to a document. The input and output PDF documents are created as streams (in this example, as file streams). The `Signer` object is used to apply the digital time-stamp. Non-critical processing errors raise a `Warning` event. It is recommended to listen for these events, and review the `WarningCategory` to determine if further action is needed. **.NET:** ```csharp // Open the input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a stream for the output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Add the document time-stamp using var outDoc = signer.AddTimestamp(inDoc, timestamp, outStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); // Add the document time-stamp Document outDoc = signer.addTimestamp(inDoc, timestamp, outStr); ``` ## Full example **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); // Create time-stamp configuration session.TimestampUrl = timeStampUrl; var timestamp = session.CreateTimestamp(); // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create stream for output file using var outStr = File.Create(outPath); // Create the Signer object Signer signer = new Signer(); // Create an event listener to listen for warning events that are raised and write them to console signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message); // Add the document time-stamp using var outDoc = signer.AddTimestamp(inDoc, timestamp, outStr); ``` **Java:** ```java // Create a session to the built-in cryptographic provider try (Provider session = new Provider()) { // Configure URL of the trusted time-stamp authority (TSA) session.setTimestampUrl(timeStampUrl); // Create time-stamp configuration TimestampConfiguration timestamp = session.createTimestamp(); // Create the Signer object Signer signer = new Signer(); // (optional) Create an event listener to listen for warning events that are raised and write them to console signer.addWarningListener((e) -> { System.out.format("Warning - %s: %s: %s", e.getCategory(), e.getContext(), e.getMessage()); }); try ( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create output stream FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Add the document time-stamp Document outDoc = signer.addTimestamp(inDoc, timestamp, outStr)) { } } ``` :::info[Signature visual appearance] You can also apply a visual appearance to the signatures. For more information, see [Create a signature visual appearance](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/signature-appearance) page. :::note[Signing PDF/A documents] During the [conversion process from PDF to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa), any signatures are removed from the file before it is converted to PDF/A for archival. Therefore we recommend files that require archiving should be [archived to PDF/A format](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) before any digital signatures are applied. --- ## Validate signatures in a signed PDF document The Pdftools SDK lets you validate digital signatures that have been added to [approve](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document) or [certify](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-certify) a PDF document. The validation process can reference online and offline sources such as: - Certificates, OCSP and CRL data embedded in the PDF file - Certificates, OCSP and CRL data downloaded from online sources - Certificates stored on the local file system - Certificates stored in the system's default trust store :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/SignaturesValidate)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/SignaturesValidate)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/SignaturesValidate)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/SignaturesValidate)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/SignaturesValidate)**. This example shows how to validate a digital signature using certificate information embedded in the PDF file, and a Custom Trust List built from certificate files stored on the local file system. **Steps to validate signatures in a document**: 1. [Create a validator object](#create-a-validator-object). 2. [Configure the validation parameters](#configure-the-validation-parameters). 3. [(Optional) Add certificates for offline validation](#add-certificates-for-offline-validation). 4. [Open and validate the document](#open-and-validate-the-document). 5. [Check and output the results](#check-and-output-the-results) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Create a Validator object The `Validator` object validates the signatures in the input PDF document against trusted sources. It is used to process the signatures as defined in the [validation parameters](#configure-the-validation-parameters) and calculate the overall validation result. **.NET:** ```csharp // Create a Validator object var validator = new Validator(); ``` **Java:** ```java // Create a Validator object Validator validator = new Validator(); ``` ## Configure the validation parameters The validator object lets you configure the validation process to handle your business logic. For example, you can validate all signatures in a document and use several trusted sources for signature validation. To do this, you can use the `Default` profile and the `SignatureSelector.ALL`. **.NET:** ```csharp // Use the default validation profile as a base for further settings var profile = new Profiles.Default(); // Validate ALL signatures in the document (not only the latest) var signatureSelector = SignatureSelector.All; ``` **tip: You can adjust the validation settings to your specific business case using the profile's `ValidationOptions`, `SigningCertTrustConstraints`, and `TimeStampTrustConstraints`.** **Java:** ```java // Use the default validation profile as a base for further settings Profile profile = new Default(); // Validate ALL signatures in the document (not only the latest) SignatureSelector signatureSelector = SignatureSelector.ALL; ``` **tip: You can adjust the validation settings to your specific business case using the profile's `getValidationOptions`, `getSigningCertTrustConstraints`, and `getTimeStampTrustConstraints`.** ## Add certificates for offline validation Certificate files (such as PFX or CER) from the local file system can be added as trusted sources using a `CustomTrustList`. **.NET:** ```csharp // create a CustomTrustList to hold the certificates var ctl = new CustomTrustList(); // Iterate through files in the certificate directory and add certificates // to the custom trust list if (Directory.Exists(certDir)) { var directoryListing = Directory.EnumerateFiles(certDir); foreach (string fileName in directoryListing) { try { using var certStr = File.OpenRead(fileName); if (fileName.EndsWith(".cer") || fileName.EndsWith(".pem")) { ctl.AddCertificates(certStr); } else if (fileName.EndsWith(".p12") || fileName.EndsWith(".pfx")) { // If a password is required, use addArchive(certStr, password). ctl.AddArchive(certStr); } } catch (Exception e) { Console.WriteLine("Could not add certificate '" + fileName + "' to custom trust list: " + e.Message); } } } else { // Handle the case where dir is not a directory Console.WriteLine("Directory " + certDir + " is missing. No certificates were added to the custom trust list."); } Console.WriteLine(); // Assign the custom trust list to the validation profile profile.CustomTrustList = ctl; // Allow validation from embedded file sources and the custom trust list var vo = profile.ValidationOptions; vo.TimeSource = TimeSource.ProofOfExistence | TimeSource.ExpiredTimeStamp | TimeSource.SignatureTime; vo.CertificateSources = DataSource.EmbedInSignature | DataSource.EmbedInDocument | DataSource.CustomTrustList; // Disable revocation checks. profile.SigningCertTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck; profile.TimeStampTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck; ``` **Java:** ```java // create a CustomTrustList to hold the certificates CustomTrustList ctl = new CustomTrustList(); // Iterate through files in the certificate directory and add certificates // to the custom trust list File dir = new File(certDir); File[] directoryListing = dir.listFiles(); if (directoryListing != null) { for (File child : directoryListing) { String fileName = child.getName(); try ( FileStream certStr = new FileStream(child.getPath(), FileStream.Mode.READ_ONLY)) { if (fileName.endsWith(".cer") || fileName.endsWith(".pem")) { ctl.addCertificates(certStr); } else if (fileName.endsWith(".p12") || fileName.endsWith(".pfx")) { // If a password is required, use addArchive(certStr, password). ctl.addArchive(certStr); } } catch (Exception e) { System.out.println("Could not add certificate '" + child.getName() + "' to custom trust list: " + e.getMessage()); } } } else { // Handle the case where dir is not a directory System.out.println("Directory " + certDir + " is missing. No certificates were added to the custom trust list."); } System.out.println(); // Assign the custom trust list to the validation profile profile.setCustomTrustList(ctl); // Allow validation from embedded file sources and the custom trust list ValidationOptions vo = profile.getValidationOptions(); vo.setTimeSource(EnumSet.of(TimeSource.PROOF_OF_EXISTENCE, TimeSource.EXPIRED_TIME_STAMP, TimeSource.SIGNATURE_TIME)); vo.setCertificateSources(EnumSet.of(DataSource.EMBED_IN_SIGNATURE, DataSource.EMBED_IN_DOCUMENT, DataSource.CUSTOM_TRUST_LIST)); // Disable revocation checks. profile.getSigningCertTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK); profile.getTimeStampTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK); ``` **tip: If you are using a Java `KeyStore` that has already been loaded, for example `ks`, you can use a `MemoryStream` to add the certificate to the `CustomTrustList`.** ```java // Create an OutputStream to write the KeyStore to (into memory) ByteArrayOutputStream os = new ByteArrayOutputStream(); // Write the KeyStore to the OutputStream ks.store(os, password.toCharArray()); // Put the OutputStream bytes into a MemoryStream Stream certStr = new MemoryStream(os.toByteArray()); // Create a CustomTrustList to hold the certificates CustomTrustList ctl = new CustomTrustList(); // Add the MemoryStream to the CustomTrustList ctl.addArchive(certStr, password); ``` The `KeyStore` must be of type `PKCS12`. For more information on the `KeyStore`, refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html). ## Open and validate the document After instantiating the validator object and configuring the validation profile, you are ready to validate the digital signatures in a document. The input document is created as a stream (in this example, as file streams). The validator object is used to validate the digital signatures. **.NET:** ```csharp using var inStr = File.OpenRead(inputFile); // Open input document // If a password is required, use Open(inStr, password) using var document = Document.Open(inStr); // Run the validate method passing the document, profile, and selector var results = validator.Validate(document, profile, signatureSelector); ``` **Java:** ```java FileStream inStr = new FileStream(inputFile, FileStream.Mode.READ_ONLY); // Open input document // If a password is required, use open(inStr, password) Document document = Document.open(inStr); // Run the validate method passing the document, profile, and selector ValidationResults results = validator.validate(document, profile, signatureSelector); ``` ## Check and output the results ### Check validation results When validation is completed, the validator object returns a `ValidationResults` object that contains all the information obtained during the validation process. This list contains a `ValidationResult` object for each signature with all the required information needed to build custom business logic. In this example, all available information is printed to the console. **.NET:** ```csharp // Print results foreach (var result in results) { var field = result.SignatureField; Console.WriteLine(field.FieldName + " of " + field.Name); try { Console.WriteLine(" - Revision : " + (field.Revision.IsLatest ? "latest" : "intermediate")); } catch (Exception ex) { Console.WriteLine("Unable to validate document Revision: " + ex.Message); } PrintContent(result.SignatureContent, field.IsFullRevisionCovered); Console.WriteLine(); } ``` **note: To implement `PrintContent`, see [print and to string functions](#print-and-to-string-functions).** **Java:** ```java // Print results results.forEach(result -> { SignedSignatureField field = result.getSignatureField(); System.out.println(field.getFieldName() + " of " + field.getName()); try { System.out.println(" - Revision : " + (field.getRevision().getIsLatest() ? "latest" : "intermediate")); } catch (Exception ex) { System.out.println("Unable to validate document Revision: " + ex.getMessage()); } printContent(result.getSignatureContent(), field.getIsFullRevisionCovered()); System.out.println(); }); ``` **note: To implement `printContent`, see [print and to string functions](#print-and-to-string-functions).** ### Check constraint events In addition to the validation results, the validator object raises constraint events for each signature `Constraint` checked. A handler function can listen to these events to track the progress of the validation process. This way, you can link any errors to the signature causing the issue. In this example, a simple console printer is used to output the signature information. **.NET:** ```csharp validator.Constraint += (s, e) => { Console.WriteLine(" - " + e.Signature.Name + (e.DataPart.Length > 0 ? (": " + e.DataPart) : "") + ": " + ConstraintToString(e.Indication, e.SubIndication, e.Message)); }; ``` **note: To implement `ConstraintToString`, see [print and to string functions](#print-and-to-string-functions).** **Java:** ```java validator.addConstraintListener(e -> { System.out.println(" - " + e.getSignature().getName() + (e.getDataPart().length() > 0 ? (": " + e.getDataPart()) : "") + ": " + constraintToString(e.getIndication(), e.getSubIndication(), e.getMessage(), true)); }); ``` **note: To implement `constraintToString`, see [print and to string functions](#print-and-to-string-functions).** ## Full example **.NET:** ```csharp // Use the default validation profile as a base for further settings var profile = new Default(); // For offline operation, build a custom trust list from the file system // and disable external revocation checks if (certDir != null && certDir.Length != 0) { Console.WriteLine("Using 'offline' validation mode with custom trust list."); Console.WriteLine(); // create a CustomTrustList to hold the certificates var ctl = new CustomTrustList(); // Iterate through files in the certificate directory and add certificates // to the custom trust list if (Directory.Exists(certDir)) { var directoryListing = Directory.EnumerateFiles(certDir); foreach (string fileName in directoryListing) { try { using var certStr = File.OpenRead(fileName); if (fileName.EndsWith(".cer") || fileName.EndsWith(".pem")) { ctl.AddCertificates(certStr); } else if (fileName.EndsWith(".p12") || fileName.EndsWith(".pfx")) { // If a password is required, use addArchive(certStr, password). ctl.AddArchive(certStr); } } catch (Exception e) { Console.WriteLine("Could not add certificate '" + fileName + "' to custom trust list: " + e.Message); } } } else { // Handle the case where dir is not a directory Console.WriteLine("Directory " + certDir + " is missing. No certificates were added to the custom trust list."); } Console.WriteLine(); // Assign the custom trust list to the validation profile profile.CustomTrustList = ctl; // Allow validation from embedded file sources and the custom trust list var vo = profile.ValidationOptions; vo.TimeSource = TimeSource.ProofOfExistence | TimeSource.ExpiredTimeStamp | TimeSource.SignatureTime; vo.CertificateSources = DataSource.EmbedInSignature | DataSource.EmbedInDocument | DataSource.CustomTrustList; // Disable revocation checks. profile.SigningCertTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck; profile.TimeStampTrustConstraints.RevocationCheckPolicy = RevocationCheckPolicy.NoCheck; } // Validate ALL signatures in the document (not only the latest) var signatureSelector = SignatureSelector.All; // Create the validator object and event listeners var validator = new Validator(); validator.Constraint += (s, e) => { Console.WriteLine(" - " + e.Signature.Name + (e.DataPart.Length > 0 ? (": " + e.DataPart) : "") + ": " + ConstraintToString(e.Indication, e.SubIndication, e.Message)); }; try { using var inStr = File.OpenRead(inputFile); // Open input document // If a password is required, use Open(inStr, password) using var document = Document.Open(inStr); // Run the validate method passing the document, profile and selector Console.WriteLine("Validation Constraints"); var results = validator.Validate(document, profile, signatureSelector); Console.WriteLine(); Console.WriteLine("Signatures validated: " + results.Count); Console.WriteLine(); // Print results foreach (var result in results) { var field = result.SignatureField; Console.WriteLine(field.FieldName + " of " + field.Name); try { Console.WriteLine(" - Revision : " + (field.Revision.IsLatest ? "latest" : "intermediate")); } catch (Exception ex) { Console.WriteLine("Unable to validate document Revision: " + ex.Message); } PrintContent(result.SignatureContent, field.IsFullRevisionCovered); Console.WriteLine(); } return 0; } catch (Exception ex) { Console.WriteLine("Unable to validate file: " + ex.Message); return 5; } ``` **Java:** ```java // Use the default validation profile as a base for further settings Profile profile = new Default(); // For offline operation, build a custom trust list from the file system // and disable external revocation checks if (certDir != null && !certDir.isEmpty()) { System.out.println("Using 'offline' validation mode with custom trust list."); System.out.println(); // create a CustomTrustList to hold the certificates CustomTrustList ctl = new CustomTrustList(); // Iterate through files in the certificate directory and add certificates // to the custom trust list File dir = new File(certDir); File[] directoryListing = dir.listFiles(); if (directoryListing != null) { for (File child : directoryListing) { String fileName = child.getName(); try ( FileStream certStr = new FileStream(child.getPath(), FileStream.Mode.READ_ONLY)) { if (fileName.endsWith(".cer") || fileName.endsWith(".pem")) { ctl.addCertificates(certStr); } else if (fileName.endsWith(".p12") || fileName.endsWith(".pfx")) { // If a password is required, use addArchive(certStr, password). ctl.addArchive(certStr); } } catch (Exception e) { System.out.println("Could not add certificate '" + child.getName() + "' to custom trust list: " + e.getMessage()); } } } else { // Handle the case where dir is not a directory System.out.println("Directory " + certDir + " is missing. No certificates were added to the custom trust list."); } System.out.println(); // Assign the custom trust list to the validation profile profile.setCustomTrustList(ctl); // Allow validation from embedded file sources and the custom trust list ValidationOptions vo = profile.getValidationOptions(); vo.setTimeSource(EnumSet.of(TimeSource.PROOF_OF_EXISTENCE, TimeSource.EXPIRED_TIME_STAMP, TimeSource.SIGNATURE_TIME)); vo.setCertificateSources(EnumSet.of(DataSource.EMBED_IN_SIGNATURE, DataSource.EMBED_IN_DOCUMENT, DataSource.CUSTOM_TRUST_LIST)); // Disable revocation checks. profile.getSigningCertTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK); profile.getTimeStampTrustConstraints().setRevocationCheckPolicy(RevocationCheckPolicy.NO_CHECK); } // Validate ALL signatures in the document (not only the latest) SignatureSelector signatureSelector = SignatureSelector.ALL; // Create the validator object and event listeners Validator validator = new Validator(); validator.addConstraintListener(e -> { System.out.println(" - " + e.getSignature().getName() + (e.getDataPart().length() > 0 ? (": " + e.getDataPart()) : "") + ": " + constraintToString(e.getIndication(), e.getSubIndication(), e.getMessage(), true)); }); try ( FileStream inStr = new FileStream(inputFile, FileStream.Mode.READ_ONLY); // Open input document // If a password is required, use open(inStr, password) Document document = Document.open(inStr); ) { // Run the validate method passing the document, profile and selector System.out.println("Validation Constraints"); ValidationResults results = validator.validate(document, profile, signatureSelector); System.out.println(); System.out.println("Signatures validated: " + results.size()); System.out.println(); // Print results results.forEach(result -> { SignedSignatureField field = result.getSignatureField(); System.out.println(field.getFieldName() + " of " + field.getName()); try { System.out.println(" - Revision : " + (field.getRevision().getIsLatest() ? "latest" : "intermediate")); } catch (Exception ex) { System.out.println("Unable to validate document Revision: " + ex.getMessage()); } Boolean isFullRevisionCovered = null; try { isFullRevisionCovered = result.getSignatureField().getIsFullRevisionCovered(); } catch (Exception ex) { System.out.println("Unable to determine full revision coverage: " + ex.getMessage()); } printContent(result.getSignatureContent(), isFullRevisionCovered); System.out.println(); }); return 0; } catch (Exception ex) { System.out.println("Unable to validate file: " + ex.getMessage()); return 5; } ``` #### Print and to string functions The following print and to string functions let you list all the properties of the signatures and the signature results. **.NET:** For example, you can use `PrintContent` to print certification details such as subject, issuer, and validity. Using `ConstraintsToString`, you can convert a constraint to a string representation. ```csharp // Helper functions to print signature validation details private static void PrintContent(SignatureContent content, bool? isFullRevisionCovered) { if(content != null) { Console.WriteLine(" - Validity : " + ConstraintToString(content.Validity, isFullRevisionCovered)); switch (content) { case UnsupportedSignatureContent: break; case CmsSignatureContent signature: { Console.WriteLine(" - Validation: " + signature.ValidationTime + " from " + signature.ValidationTimeSource); Console.WriteLine(" - Hash : " + signature.HashAlgorithm); Console.WriteLine(" - Signing Cert"); PrintContent(signature.SigningCertificate); Console.WriteLine(" - Chain"); foreach (var cert in signature.CertificateChain) { Console.WriteLine(" - Issuer Cert " + (signature.CertificateChain.IndexOf(cert) + 1)); PrintContent(cert); } Console.WriteLine(" - Chain : " + (signature.CertificateChain.IsComplete ? "complete" : "incomplete") + " chain"); Console.WriteLine(" Time-Stamp"); PrintContent(signature.TimeStamp, null); break; } case TimeStampContent timeStamp: { Console.WriteLine(" - Validation: " + timeStamp.ValidationTime + " from " + timeStamp.ValidationTimeSource); Console.WriteLine(" - Hash : " + timeStamp.HashAlgorithm); Console.WriteLine(" - Time : " + timeStamp.Date); Console.WriteLine(" - Signing Cert"); PrintContent(timeStamp.SigningCertificate); Console.WriteLine(" - Chain"); foreach (var cert in timeStamp.CertificateChain) { Console.WriteLine(" - Issuer Cert " + (timeStamp.CertificateChain.IndexOf(cert) + 1)); PrintContent(cert); } Console.WriteLine(" - Chain : " + (timeStamp.CertificateChain.IsComplete ? "complete" : "incomplete") + " chain"); break; } default: Console.WriteLine("Unsupported signature content type " + content.GetType().Name); break; } } else { Console.WriteLine(" - null"); } } private static void PrintContent(Certificate cert) { if(cert != null) { Console.WriteLine(" - Subject : " + cert.SubjectName); Console.WriteLine(" - Issuer : " + cert.IssuerName); Console.WriteLine(" - Validity : " + cert.NotBefore + " - " + cert.NotAfter); try { Console.WriteLine(" - Fingerprint: " + FormatSha1Digest(new BigInteger(SHA1.Create().ComputeHash(cert.RawData)).ToByteArray(), "-")); } catch (Exception ex) { Console.WriteLine(ex.Message); } Console.WriteLine(" - Source : " + cert.Source); Console.WriteLine(" - Validity : " + ConstraintToString(cert.Validity, null)); } else { Console.WriteLine(" - null"); } } private static String ConstraintToString(ConstraintResult constraint, bool? isFullRevisionCovered) { return ConstraintToString(constraint.Indication, constraint.SubIndication, constraint.Message, isFullRevisionCovered); } private static string ConstraintToString(Indication indication, SubIndication subIndication, string message, bool? isFullRevisionCovered = null) { if (isFullRevisionCovered is null || isFullRevisionCovered.Value) { return (indication == Indication.Valid ? "" : indication == Indication.Indeterminate ? "?" : "!") + subIndication + " " + message; } string byteRangeInvalid = "!Invalid signature byte range."; return indication == Indication.Valid ? byteRangeInvalid : $"{byteRangeInvalid} {subIndication} {message}"; } // Helper function to generate a delimited SHA-1 digest string private static String FormatSha1Digest(byte[] bytes, String delimiter) { var result = new StringBuilder(); foreach (byte aByte in bytes) { int number = (int)aByte & 0xff; String hex = number.ToString("X2"); result.Append(hex.ToUpper() + delimiter); } return result.ToString().Substring(0, result.Length - delimiter.Length); } ``` **Java:** For example, you can use `printContent` to print certification details such as subject, issuer, and validity. Using `constraintsToString`, you can convert a constraint to a string representation. ```java // Helper functions to print signature validation details private static void printContent(SignatureContent content, Boolean isFullRevisionCovered) { if(content != null) { System.out.println(" - Validity : " + constraintToString(content.getValidity(), isFullRevisionCovered)); switch (content.getClass().getSimpleName()) { case "UnsupportedSignatureContent": break; case "CmsSignatureContent": { CmsSignatureContent signature = (CmsSignatureContent)content; System.out.println(" - Validation: " + signature.getValidationTime() + " from " + signature.getValidationTimeSource()); System.out.println(" - Hash : " + signature.getHashAlgorithm()); System.out.println(" - Signing Cert"); printContent(signature.getSigningCertificate()); System.out.println(" - Chain"); signature.getCertificateChain().forEach(cert -> { System.out.println(" - Issuer Cert " + (signature.getCertificateChain().indexOf(cert) + 1)); printContent(cert); }); System.out.println(" - Chain : " + (signature.getCertificateChain().getIsComplete() ? "complete" : "incomplete") + " chain"); System.out.println(" Time-Stamp"); printContent(signature.getTimeStamp(), true); break; } case "TimeStampContent": { TimeStampContent timeStamp = (TimeStampContent)content; System.out.println(" - Validation: " + timeStamp.getValidationTime() + " from " + timeStamp.getValidationTimeSource()); System.out.println(" - Hash : " + timeStamp.getHashAlgorithm()); System.out.println(" - Time : " + timeStamp.getDate()); System.out.println(" - Signing Cert"); printContent(timeStamp.getSigningCertificate()); System.out.println(" - Chain"); timeStamp.getCertificateChain().forEach(cert -> { System.out.println(" - Issuer Cert " + (timeStamp.getCertificateChain().indexOf(cert) + 1)); printContent(cert); }); System.out.println(" - Chain : " + (timeStamp.getCertificateChain().getIsComplete() ? "complete" : "incomplete") + " chain"); break; } default: System.out.println("Unsupported signature content type " + content.getClass().getName()); break; } } else { System.out.println(" - null"); } } private static void printContent(Certificate cert) { if(cert != null) { System.out.println(" - Subject : " + cert.getSubjectName()); System.out.println(" - Issuer : " + cert.getIssuerName()); System.out.println(" - Validity : " + cert.getNotBefore() + " - " + cert.getNotAfter()); try { System.out.println(" - Fingerprint: " + formatSha1Digest(new java.math.BigInteger(1, (MessageDigest.getInstance("SHA-1").digest(cert.getRawData()))).toByteArray(), "-")); } catch (Exception ex) { System.out.println(ex.getMessage()); } System.out.println(" - Source : " + cert.getSource()); System.out.println(" - Validity : " + constraintToString(cert.getValidity(), true)); } else { System.out.println(" - null"); } } private static String constraintToString(ConstraintResult constraint, Boolean isFullRevisionCovered) { return constraintToString(constraint.getIndication(), constraint.getSubIndication(), constraint.getMessage(), isFullRevisionCovered); } private static String constraintToString(Indication indication, SubIndication subIndication, String message, Boolean isFullRevisionCovered) { if (isFullRevisionCovered == null || isFullRevisionCovered) { return (indication == Indication.VALID ? "" : (indication == Indication.INDETERMINATE ? "?" : "!")) + "" + subIndication + " " + message; } String byteRangeInvalid = "!Invalid signature byte range."; if (indication == Indication.VALID) return byteRangeInvalid; else return byteRangeInvalid + " " + subIndication + " " + message; } // Helper function to generate a delimited SHA-1 digest string private static String formatSha1Digest(byte[] bytes, String delimiter) { StringBuilder result = new StringBuilder(); for (byte aByte : bytes) { int decimal = (int) aByte & 0xff; String hex = Integer.toHexString(decimal); if (hex.length() % 2 == 1) hex = "0" + hex; result.append(hex.toUpperCase() + delimiter); } return result.substring(0, result.length() - delimiter.length()); } ``` --- ## Create a signature visual appearance A signature can have a visual appearance on a PDF document page. For example, the signature can appear as a company stamp or an individual's handwritten signature. The Pdftools SDK lets you configure a visual appearance using an XML or a JSON file. The visual appearance can contain text, images, and pages of PDFs. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/VisualSignature)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/VisualSignature)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/VisualSignature)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/VisualSignature)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/VisualSignature)**. **info: The Pdftools SDK creates invisible signatures by default, because a signature's visual appearance can obscure important content on the page. The validity of the signature is not affected by its visual appearance.** **Steps to add a signature visual appearance**: 1. [Configure visual appearance](#configure-visual-appearance) 2. [Apply text variables](#apply-text-variables) - [Pre-defined text variables](#pre-defined-text-variables) - [Custom text variables](#custom-text-variables) 3. [Create a signature and set its visual appearance](#create-a-signature-and-set-its-visual-appearance) 4. [Create a signature visual appearance for an existing signature field](#create-a-signature-visual-appearance-for-an-existing-signature-field) --- ## Configure visual appearance Configure the signature visual appearance either in an XML file or in a JSON file. The appearance comprises multiple text elements, images, or pages of PDFs that are placed inside the surrounding visual appearance container. Examples: **XML:** ```xml Signed by: Max Muster Signing date: [signature:date,localtime,%d.%m.%Y %H:%M:%S] Company: [custom:company] Powered by: ``` **JSON:** ```json { "size": "130pt 90pt", "content": [ { "image": "DigitalSignature.jpg" }, { "pdf": "butterfly.pdf", "margin-left": "110pt", "width": "12pt", "height": "12pt", "margin-top": "5pt" }, { "image": "pdftools-icon.png", "margin-left": "114pt", "width": "8pt", "margin-top": "79pt" }, { "margin-top": "20pt", "margin-left": "1pt", "text-align": "left", "font-size": "10", "text": [ "Signed by: ", { "color": "1 0.2 0", "font": "Bell MT Bold", "text-mode": "stroke", "text": "Max Muster" } ] }, { "margin-top": "43pt", "margin-left": "1pt", "text-align": "left", "font-size": "6", "text": [ "Signing date: ", { "font": "Courier", "color": "0.2 0.2 0.2", "text": "[signature:date,localtime,%d.%m.%Y %H:%M:%S]" } ] }, { "margin-top": "55pt", "margin-left": "1pt", "text-align": "left", "font-size": "6", "text": [ "Company: ", { "font": "OpenSans-Semibold.ttf", "color": "0 0 1", "text": "[custom:company]" } ] }, { "font-size": "4", "font": "Arial", "margin-top": "78pt", "margin-left": "90pt", "text": [ "Powered by:" ] } ] } ``` **note: The XML or JSON file specifies only the size of the visual appearance container but not its actual location. In the case of [signing](#create-a-signature-and-set-its-visual-appearance), the location can be explicitly specified in the code, while for [signing of an existing unsigned signature field](#create-a-signature-visual-appearance-for-an-existing-signature-field), the location is predetermined.** :::note[General definition of XML schema file] The [schema file](https://www.pdf-tools.com/docs/files/pdf-tools-sdk/schema-visual-appearance-version1.0.xsd) defines the visual appearance of an XML file. The structure of a JSON file is equivalent. The Pdftools SDK creates the appearance according to the configuration as follows: **.NET:** ```csharp // Create appearance from an XML using var appStream = File.OpenRead(appearanceXml); Appearance appearance = Appearance.CreateFromXml(appStream); ``` ```csharp // Create appearance from a JSON file using var appStream = File.OpenRead(appearanceJson); Appearance appearance = Appearance.CreateFromJson(appStream); ``` **Java:** ```java try ( // Create appearance from an XML FileStream appConfigStr = new FileStream(appearanceXml, FileStream.Mode.READ_ONLY)) { Appearance appearance = Appearance.createFromXml(appConfigStr); } ``` ```java try ( // Create appearance from a JSON file FileStream appConfigStr = new FileStream(appearanceJson, FileStream.Mode.READ_ONLY)) { Appearance appearance = Appearance.createFromJson(appConfigStr); } ``` ## Apply text variables Text variables are placeholders in the text. Placeholders are substituted with specific values just before signing the document. There are two types of text variables: - Pre-defined variables (such as location, title, author) - Custom variables (defined by you) In other words, the text can be parametrized using text variables, either by pre-defined text variables or by custom text variables. Text variables take the general form of `[:]`. They are replaced by their actual values just before signing the document. ### Pre-defined text variables There are a couple of pre-defined text variables for which values are set during code execution: - `[signature:contactinfo]` - `[signature:location]` - `[signature:reason]` - `[document:title]` - `[document:author]` - `[document:subject]` The special variable `[signature:date,,]` describes the signing date. `` takes the values `utc` or `localtime`. Different date formats `` can be specified. Some typical formats are: - EU: `%d.%m.%Y %H:%M:%S` - US: `%m/%d/%Y %H:%M:%S` - UK: `%d/%m/%Y %H:%M:%S` For a complete description of the date formatting options, consult the [strftime reference](https://strftime.org/). ### Custom text variables You can also store custom text variables and their values as key-value pairs in the map `Appearance.CustomTextVariables`. For more information, see an example in [Create a signature and set visual appearance](#create-a-signature-and-set-its-visual-appearance) section. The `value` is accessed in the text by `[custom:]`. ## Create a signature and set its visual appearance :::tip[Get started] Learn more about [signing a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new BuiltIn.Provider(); // Open certificate file using var pfxStr = File.OpenRead(certificateFile); // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.CreateSignatureFromCertificate(pfxStr, password); // Create appearance from either an XML or a JSON file using var appStream = File.OpenRead(appConfigFile); if (Path.GetExtension(appConfigFile) == ".xml") signature.Appearance = Appearance.CreateFromXml(appStream); else signature.Appearance = Appearance.CreateFromJson(appStream); signature.Appearance.PageNumber = 1; signature.Appearance.CustomTextVariables.Add("company", "Daily Planet"); // Set location of appearance signature.Appearance.Bottom = Length.pt(20); signature.Appearance.Right = Length.pt(15); // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create stream for output file using var outStr = File.Create(outPath); // Sign the input document using var outDoc = new Signer().Sign(inDoc, signature, outStr); ``` **Java:** ```java try ( // Create a session to the built-in cryptographic provider Provider session = new Provider(); // Open certificate file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY)) { // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); try ( // Create appearance from either an XML or a JSON file FileStream appConfigStr = new FileStream(appConfigFile, FileStream.Mode.READ_ONLY)) { if (appConfigFile.toLowerCase().endsWith(".xml")) signature.setAppearance(Appearance.createFromXml(appConfigStr)); else signature.setAppearance(Appearance.createFromJson(appConfigStr)); signature.getAppearance().setPageNumber(1); signature.getAppearance().getCustomTextVariables().put("company", "Daily Planet"); // Set location of appearance signature.getAppearance().setBottom(new Length(20)); signature.getAppearance().setTop(new Length(15)); try( // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr); // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = new Signer().sign(inDoc, signature, outStr)) { } } } ``` ## Create a signature visual appearance for an existing signature field :::tip[Get started] Learn more about [signing a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). You can apply a signature visual appearance when signing an existing unsigned signature field. In the following example, the input PDF's first unsigned signature field (of potentially many unsigned signature fields) is signed, and a visual appearance is added. **.NET:** ```csharp // Create a session to the built-in cryptographic provider using var session = new PdfTools.Crypto.Providers.BuiltIn.Provider(); // Create signature configuration from PFX (or P12) file using var pfxStr = File.OpenRead(certificateFile); Signature signature = session.CreateSignatureFromCertificate(pfxStr, password); // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Choose first signature field foreach (var field in inDoc.SignatureFields) { if (field != null) { signature.FieldName = field.FieldName; break; } } // Create stream for output file using var outStr = File.Create(outPath); // Create appearance from either an XML or a JSON file using var appStream = File.OpenRead(appConfigFile); if (Path.GetExtension(appConfigFile) == ".xml") signature.Appearance = Appearance.CreateFromXml(appStream); else signature.Appearance = Appearance.CreateFromJson(appStream); signature.Appearance.CustomTextVariables.Add("company", "Daily Planet"); // Sign the input document using var outDoc = new Signer().Sign(inDoc, signature, outStr); ``` **Java:** ```java try ( // Create a session to the built-in cryptographic provider Provider session = new Provider(); // Open certificate file FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY); // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStr);) { // Create signature configuration from PFX (or P12) file SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password); // Choose first signature field for (int i = 0; i < inDoc.getSignatureFields().size(); i++) { if (inDoc.getSignatureFields().get(i) != null) { signature.setFieldName(inDoc.getSignatureFields().get(i).getFieldName()); break; } } try ( // Create appearance from either an XML or a JSON file FileStream appConfigStr = new FileStream(appConfigFile, FileStream.Mode.READ_ONLY)) { if (appConfigFile.toLowerCase().endsWith(".xml")) signature.setAppearance(Appearance.createFromXml(appConfigStr)); else signature.setAppearance(Appearance.createFromJson(appConfigStr)); signature.getAppearance().getCustomTextVariables().put("company", "Daily Planet"); try( // Create a stream for the output file FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); // Sign the input document Document outDoc = new Signer().sign(inDoc, signature, outStr)) { } } } ``` --- ## Use a time-stamp authority A time-stamp authority (TSA) provides trusted, cryptographically secure time-stamp information. This time-stamp information can be used to apply a digital time-stamp to a document, which verifies that the document existed at a point in time, and that the content of the document has not been changed. The TSA must support the time-stamp protocol as defined in the [IETF RFC 3161](https://www.ietf.org/rfc/rfc3161.txt). The [GlobalSign](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-globalsign) and [Swisscom](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-swisscom) cryptographic providers have their own TSA with which the user can generate trusted time-stamp information. The [Built-in](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-builtin) and [PKCS#11](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/provider-pkcs11) cryptographic providers require a third-party TSA to be configured. To configure the TSA, you must pass the [URI of the TSA](#time-stamp-authority-uri) to the cryptographic provider and call the `CreateTimestamp` method. ## Time-stamp authority URI When [applying a digital time-stamp to a document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-timestamp), the time-stamp authority (TSA) URI must be passed to the cryptographic provider in the `TimestampUrl` property. The `TimestampUrl` property value must be a URI with the following elements: ``` http[s]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›] ``` Where: - `http/https`: Protocol for connecting to the TSA. - `‹user›:‹password›` (optional): Credentials for connecting to the TSA (basic authorization). - `‹host›`: Hostname of the TSA. - `‹port›`: Port for connecting to the TSA. - `‹resource›`: The resource. ## HTTPS connections When connecting to the time-stamp authority using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified using the system's default trust store (CA certificate store). For information about configuring the trust store, see [Configure HTTPS connections](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#configure-https-connections). ## Proxy server In a secured environment, the firewall must be configured to allow a connection to the time-stamp authority. If a [proxy server](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/configure-digital-signing#use-a-proxy-server) is used, the following MIME types must be supported: - `application/timestamp-query` - `application/timestamp-reply` --- ## Validate PDF documents With the Pdftools SDK, you can validate PDF documents according to various PDF specifications. The Pdftools SDK lets you validate the following standards: | PDF | PDF/A | | --------------------- | --------------------- | | PDF Reference 1.3-1.6 | PDF/A-1 (ISO 19005-1) | | PDF 1.7 (ISO 32000-1) | PDF/A-2 (ISO 19005-2) | | PDF 2.0 (ISO 32000-2) | PDF/A-3 (ISO 19005-3) | You can verify PDF documents in accordance with the ISO standard for PDF and also PDF/A for long­-term archiving, as well as to a specific conformance level. Additional verification tests such as checking the version number of the PDF document are also possible. You can also verify conformance to internal directives; for example, use of the right color or use of the right fonts and other specifications. You can check the conformity of individual documents and entire archives. With the Pdftools SDK, you can: - Perform PDF ­conformance in terms of lexical, syntactic, and semantic checks - Get a detailed or summarized report (log file): - Get detailed error descriptions: number, type, description, PDF object, page number - Classify by error, warning, and information - Cancel validation automatically when the first error is encountered - Determine the claimed conformance of the document - Validate conformance to corporate directives defined in custom profile ## Conformance levels **[Conformance levels](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/conformance-levels)** are determined by the PDF standard. Within the PDF/A specification standards, the following conformance levels are supported: - B (Basic) - U (Unicode, only PDF/A-2 and PDF/A-3) - A (Accessibility) ## Validation checks When you validate a PDF document with the Pdftools SDK, different **[lexical, syntactic, and semantic validation checks](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/validation-checks)** are performed according to the PDF version and conformance level. ## Validation reports You can determine how you want to receive the results of the document validation process. You can choose the reporting level: either a detailed report or a summary of error reports. The description includes every detail such as frequency, page number, or PDF object number. Verification of internal specifications (for example, standard image resolution) can occur at the same time. :::tip[Get started] Learn **[how to validate a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/validate-a-pdf)** for conformance with a PDF version, or a PDF/A standard and level. --- ## Conformance levels Conformance levels apply to [PDF/A documents](https://www.pdf-tools.com/docs/knowledge/pdf-standards#pdfa---archive) only. A conformance level defines the quality requirements for the PDF document's content. There are three conformance levels: 1. [B (Basic)](#level-b---basic) 2. [U (Unicode)](#level-u---unicode) 3. [A (Accessibility)](#level-a---accessibility) The conformance levels are incremental, meaning that the subsequent level includes the requirements of the previous level and other additional requirements. For example, all level U documents are also valid level B documents. Each PDF/A document has a claimed conformance level. The Pdftools SDK validates this level by performing specific [validation checks](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/validation-checks). For example, only PDF/A documents that claim to have Level U conformance (which can be either PDF/A-2 or PDF/A-3) are checked to determine whether they contain alternate descriptions of the content where needed. ## Level B - Basic Level B conformance determines the visual integrity of the document. It guarantees clear, long-term visual reproduction of static content in the PDF document. This is the default conformance level for all PDF/A conforming documents. ## Level U - Unicode Level U conformance guarantees the searchability of text within the PDF. Unicode text is copied to the output file, allowing it to be extracted later if required. This is for digitally created PDF/A documents and documents scanned using optical character recognition (OCR). This conformance level only applies to PDF documents that conform to [PDF/A-2](https://www.pdf-tools.com/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](https://www.pdf-tools.com/docs/knowledge/pdf-a/#pdfa-3). ## Level A - Accessibility Level A determines the semantic correctness and structure of the PDF/A document. In other words, it preserves the document's logical structure and content text stream in natural reading order. It also ensures that conforming files can be accessed by devices used by physically impaired users such as screen readers. This conformance level only applies to PDF documents that conform to [PDF/A-2](https://www.pdf-tools.com/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](https://www.pdf-tools.com/docs/knowledge/pdf-a/#pdfa-3). --- ## Reporting levels for validation --- ## Validate PDF document Validate a PDF document for conformance with a PDF version, or a PDF/A standard and level. When standard violations are encountered, you get detailed information about the type and location of the violation. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/sdk-examples-c/tree/main/ValidateSimple)**, **[C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/ValidateSimple)**, **[Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/ValidateSimple)**, **[Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/ValidateSimple)**, and **[Visual Basic](https://github.com/pdf-tools/sdk-examples-vbnet/tree/main/ValidateSimple)**. **Steps to validate a document**: 1. [Read the input document](#read-the-input-document) 2. [Create a Conformance object](#create-a-conformance-object) 3. [Create a Validator object](#create-a-validator-object) 4. [Run the Validate process](#run-the-validate-process) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Pdftools SDK license](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#initialize-the-pdftools-sdk-license)**. ## Read the input document First you need to read the PDF document you want to validate. To do this, load the input document from the file system into a read-only input `Document`. This `Document` can then later be passed to the `Validator`. **.NET:** ```csharp // Open input document using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); ``` **Java:** ```java // Open input document FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr); ``` ## Create a Conformance object The document validation process begins with the creation of a `Conformance` object. The `Conformance` object defines the PDF version, or the PDF/A standard and level, against which the document is validated. **info: The checks performed are determined by the PDF version or PDF/A standard and conformance level.** For more information on the checks performed by the Pdftools SDK, see **[Validation checks](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/validation-checks)**. This example uses the PDF/A-2 standard (`2`), with conformance level B (`Conformance.PdfALevel.B`). **.NET:** ```csharp // Create a conformance object that specifies the PDF/A standard and level against which the document is validated. var conformance = new Conformance(2, Conformance.PdfALevel.B); ``` **Java:** ```java // Create a conformance object that specifies the PDF/A standard and level against which the document is validated. Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B)); ``` ## Create a Validator object The `Validator` object validates the standards conformance of the input PDF document against the PDF version, or the PDF/A standard and level, defined in the `Conformance` object. When the Validator finds standard violations, it emits `Error` events that provide detailed information about the type of error and where the error occurred in the PDF document. A handler function can listen to the `Error` event and execute business logic based on the information contained in it. **.NET:** ```csharp // Create a Validator object and attach an Error event handler. // In this example we simply write the validation data to the console, but more complex business logic may be implemented based on the category, location, or other attributes of the validation error. var validator = new Validator(); validator.Error += (s, e) => Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " on page " + e.PageNo : ""); ``` **Java:** ```java // Create a Validator object and attach an Error event handler. // In this example, the validation data is written to the console, but more complex business logic may be implemented based on the category, location, or other attributes of the validation error. Validator validator = new Validator(); validator.addErrorListener( (Validator.Error error) -> System.out.format("- %s: %s (%s%s)%n", error.getCategory(), error.getMessage(), error.getContext(), error.getPageNo() > 0 ? String.format(" on page %d", error.getPageNo()) : "") ); ``` ## Run the Validate process After creating the `Conformance` and `Validator` objects, the final step is to call the `Validate` method. The output of this method is a `ValidationResult` which provides information about the conformance of the input document to the PDF version, or the PDF/A standard and level, that is defined in the `Conformance` object. If a `Conformance` object is not passed in the `ValidatorOptions`, the `Validate` process instead validates the conformance of the input document against the document's _claimed conformance_. The _claimed conformance_ is the level of conformance that is stored internally within the input document. **info: The input document must be a **valid PDF file format**.** Otherwise, the validation process fails. **.NET:** ```csharp // Validate the PDF/A standard and level of the document against the defined Conformance level. var options = new ValidationOptions() { Conformance = conformance }; var result = validator.Validate(inDoc, options); // Write the result of the Validate method to the console. Console.WriteLine("Document conforms to " + result.Conformance.ToString() + ": " + result.IsConforming); ``` **Java:** ```java // Validate the PDF/A standard and level of the document against the defined Conformance level. ValidationOptions options = new ValidationOptions(); options.setConformance(conformance); ValidationResult result = validator.validate(inDoc, options); // Write the result of the Validate method to the console. System.out.println("Document conforms to " + result.getConformance().toString() + ": " + result.getIsConforming()); ``` Here's an example of the output that is generated by this sample code: ``` - Metadata: The key Metadata is required but missing. (catalog) - Color: A device-specific color space (DeviceRGB) without an appropriate output intent is used. (content of page 1) Document conforms to PDF/A-2b: False ``` ## Full example **.NET:** ```csharp // Open the PDF document to validate using var inStr = File.OpenRead(inPath); using var inDoc = Document.Open(inStr); // Create a conformance object that specifies the PDF/A standard and conformance level against which the document is validated. // Here the PDF/A-2 standard with conformance Level B is used. var conformance = new Conformance(2, Conformance.PdfALevel.B); // Create a Validator object and attach an Error event handler that simply writes the validation error messages to the console. var validator = new Validator(); validator.Error += (s, e) => Console.WriteLine("- {0}: {1} ({2}{3})", e.Category, e.Message, e.Context, e.PageNo > 0 ? " on page " + e.PageNo : ""); // Validate the PDF/A Standard and Level of the document against the defined Conformance level. var options = new ValidationOptions() { Conformance = conformance }; var result = validator.Validate(inDoc, options); // Write the result of the Validate method to the console. Console.WriteLine("Document conforms to " + result.Conformance.ToString() + ": " + result.IsConforming); ``` **Java:** ```java // Open the PDF document to validate try (FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY); com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr)) { // Create a conformance object that specifies the PDF/A standard and level against which the document is validated. // Here we choose the PDF/A-2 Standard, with conformance Level B. Conformance conformance = new Conformance(new Conformance.PdfAVersion(2, Conformance.PdfAVersion.Level.B)); // Create a Validator object and attach an Error event handler that simply writes the validation error messages to the console. Validator validator = new Validator(); validator.addErrorListener( (Validator.Error error) -> System.out.format("- %s: %s (%s%s)%n", error.getCategory(), error.getMessage(), error.getContext(), error.getPageNo() > 0 ? String.format(" on page %d", error.getPageNo()) : "") ); // Validate the PDF/A standard and level of the document against the defined Conformance level. ValidationOptions options = new ValidationOptions(); options.setConformance(conformance); ValidationResult result = validator.validate(inDoc, options); // Write the result of the Validate method to the console. System.out.println("Document conforms to " + result.getConformance().toString() + ": " + result.getIsConforming()); } ``` --- ## Validation checks The Pdftools SDK performs multiple lexical, syntactic, and semantic checks when validating a PDF document according to an ISO standard or a corporate directive. The table shows details of the validation checks performed according to the **[specification](https://www.pdf-tools.com/docs/knowledge/pdf-standards)** and **[conformance level](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/conformance-levels)**. | | PDF | PDF/A-1 | PDF/A-2 & PDF/A-3 | Level U | Level A | | -------------------------------------------------------------------------------------------- | --- | ------- | ----------------- | ------- | ------- | | **Lexical checks** | | | | | | | Structure of tokens such as keywords, names, numbers, and strings | x | x | x | x | x | | Structure of the cross-reference table | x | x | x | x | x | | File positions in the trailer dictionary and cross reference table | x | x | x | x | x | | Whether a referenced object has the correct object and generation number | x | x | x | x | x | | Length attribute of stream objects | x | x | x | x | x | | No header offset | | x | x | x | x | | Contains a binary marker | | x | x | x | x | | **Syntactic checks** | | | | | | | Structure of dictionaries, arrays, indirect objects, and streams | x | x | x | x | x | | Compression errors such as CCITT, JPEG, and Flate | x | x | x | x | x | | Errors in embedded font programs | x | x | x | x | x | | Errors in ICC color profiles | x | x | x | x | x | | **Semantic checks** | | | | | | | Required entries in dictionaries, such as width entry in an image dictionary | x | x | x | x | x | | Inherited attributes | x | x | x | x | x | | Value of the parent entries in dictionaries, such as page objects | x | x | x | x | x | | Type of the dictionary entry's value, such as integer, string, or name | x | x | x | x | x | | Whether the object must be indirect or direct (for example, a page object must be an indirect object) | x | x | x | x | x | | Order of operators in content streams | x | x | x | x | x | | Number of operands of the operators | x | x | x | x | x | | Type of operands of the operators | x | x | x | x | x | | Value ranges of the operands | x | x | x | x | x | | Unknown referenced resources | x | x | x | x | x | | Operand stack overflow and underflow | x | x | x | x | x | | Inconsistent information, such as an image having both a stencil mask and soft mask | x | x | x | x | x | | Conformance to implementation limits defined by the PDF Reference | x | x | x | x | x | | No unrendered XFA forms | x | x | x | x | x | | Contains a unique file identifier | | x | x | x | x | | Contains document metadata | | x | x | x | x | | Contains embedded font programs where needed | | x | x | x | x | | Contains character to glyph mapping (encoding) information for the fonts | | x | x | x | x | | Contains an output intent if needed | | x | x | x | x | | No encryption | | x | x | x | x | | No LZW and non-standard filters | | x | x | x | x | | No JavaScript | | x | x | x | x | | No unallowed annotations | | x | x | x | x | | No unallowed actions | | x | x | x | x | | No form fields that are generated on the fly | | x | x | x | x | | No embedded PostScript code | | x | x | x | x | | No invisible, hidden or non-printable annotations | | x | x | x | x | | No device-specific color spaces | | x | x | x | x | | No unknown rendering intents | | x | x | x | x | | No image interpolation | | x | x | x | x | | No externally referenced information (external streams and reference XObjects) | | x | x | x | x | | No Open Print Interface (OPI) information | | x | x | x | x | | No alternate images | | x | x | x | x | | No color transfer and half-toning functions | | x | x | x | x | | No JPX | | x | x | x | x | | No layers | | x | x | x | x | | No transparency | | x | x | x | x | | No embedded files | | x | x | x | x | | No XRef streams | | x | x | x | x | | Conformity of metadata | | x | x | x | x | | PDF/A conformance of embedded files | | | x | x | x | | Consistency of spot colors | | | x | x | x | | Contains Unicode information of fonts where needed | | | | x | x | | Contains logical structure information (tagging) | | | | | x | | Contains alternate descriptions of content (replacement text) where needed | | | | | x | --- ## Migrate from version 1.14 or earlier Pdftools SDK 1.15+ simplifies the Java project setup. Pdftools SDK loads the native library automatically at runtime, so you no longer need platform-specific dependencies or `System.load()` / `System.loadLibrary()` calls in your code. Learn how to replace the earlier setup for Maven, Gradle, and manual JAR management. ## Maven ### Remove the earlier setup In versions 1.14 and earlier, your `pom.xml` contained two dependencies: the main JAR and a platform-specific native artifact with a classifier such as `linux-x64`, `win-x64`, or `osx-arm64`: ```xml com.pdftools pdftools-sdk 1.14.0 com.pdftools pdftools-sdk 1.14.0 linux-x64 so ``` Your Java code also contained a `System.load()` or `System.loadLibrary()` call to load the native binary before using Pdftools SDK: ```java // Remove this line System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-x64.so"); ``` ### Add the new setup Replace both dependencies with a single dependency. Remove all `System.load()` and `System.loadLibrary()` calls for Pdftools SDK from your code. ```xml com.pdftools pdftools-sdk 1.15.0 ``` This single dependency includes native binaries for all supported platforms. Pdftools SDK loads them automatically at runtime. ## Gradle ### Remove the earlier setup In versions 1.14 and earlier, your `build.gradle` contained two dependencies: the main JAR and a platform-specific native artifact: ```groovy // Remove this entire block implementation 'com.pdftools:pdftools-sdk:1.14.0' implementation 'com.pdftools:pdftools-sdk:1.14.0:linux-x64@so' ``` Your Java code also contained a `System.load()` or `System.loadLibrary()` call: ```java // Remove this line System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.14.0/pdftools-sdk-1.14.0-linux-x64.so"); ``` ### Add the new setup Replace both dependencies with a single dependency. Remove all `System.load()` and `System.loadLibrary()` calls for Pdftools SDK from your code. ```groovy implementation 'com.pdftools:pdftools-sdk:1.15.0' ``` This single dependency includes native binaries for all supported platforms. Pdftools SDK loads them automatically at runtime. ## Manual JAR management ### Remove the earlier setup In versions 1.14 and earlier, you downloaded a product kit ZIP that contained a JAR file and a `lib` directory with platform-specific native binaries: ``` lib ├── linux-x64 ├── linux-arm64 ├── osx-arm64 ├── osx-x64 ├── win-x64 ├── win-x86 └── win-arm64 ``` Your Java code contained a `System.load()` or `System.loadLibrary()` call to load the correct native binary at runtime: ```java // Remove these lines System.load(new File("lib/linux-x64/libPdfToolsSdk.so").getAbsolutePath()); // or System.loadLibrary("PdfToolsSdk"); ``` ### Add the new setup 1. Delete the earlier JAR file and the `lib` directory with native binaries (`.dll`, `.so`, `.dylib` files) from your project. 1. Download the following JARs from Maven Central: - [`pdftools-sdk-1.15.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.15.0/pdftools-sdk-1.15.0.jar) (binding layer; [sources JAR](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.15.0/pdftools-sdk-1.15.0-sources.jar), [Javadoc JAR](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/1.15.0/pdftools-sdk-1.15.0-javadoc.jar)) - [`pdftools-sdk-native-1.15.0.jar`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk-native/1.15.0/pdftools-sdk-native-1.15.0.jar) (native libraries) 1. Add both JARs to your project's classpath. 1. Remove all `System.load()` and `System.loadLibrary()` calls for Pdftools SDK from your code. The `pdftools-sdk-native` JAR bundles the native libraries, and Pdftools SDK loads them automatically at runtime. ## Further information - For the full setup instructions, see the [Java getting started guide](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java). - For other changes in version 1.15, see the [release notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes). --- ## Release notes Learn about the latest updates of: - [Pdftools SDK](#pdftools-sdk) - [Pdftools SDK Shell Tool](#pdftools-sdk-shell-tool) ## Pdftools SDK ### Version 1.17.0 24 April 2026 #### Added - **Dithering control for Fax image conversion** The Fax conversion profile exposes a dithering option, letting you switch between dithering modes when rendering PDFs to fax-ready images. For more details, refer to [Fax conversion profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#fax). #### Fixed - Before this update, PDF/A conversion incorrectly reported a device-color-space error on documents containing nested form XObjects. As a consequence, valid documents couldn't be converted to PDF/A. With this release, the converter resolves color spaces correctly. As a result, these documents convert to PDF/A as expected. - Before this release, optimizing PDFs with certain internal structures caused the optimizer to perform many redundant object comparisons. As a consequence, optimization appeared to hang and didn't complete on the affected documents. With this release, the optimizer avoids the redundant comparisons. As a result, optimization finishes in the expected time on the affected documents. - Before this update, validating a malformed PDF containing nested object streams caused unbounded recursion. As a consequence, the process crashed with a stack overflow on the affected documents. With this release, the validator detects the cycle and rejects the document with a clean validation error. As a result, malformed input can no longer crash the validator. ### Version 1.16.0 2 April 2026 #### Added - **OCR pre-processing for PDF workflows.** Apply OCR to scanned PDFs and images through Pdftools SDK workflows (PDF to PDF/A conversion, conformance validation, digital signing). Connect to an OCR service endpoint to perform recognition without changing application logic. For more details, refer to [OCR](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/). #### Fixed - Before this update, certain conversion events, such as XMP metadata information loss, weren't tracked through the Pdftools SDK error reporting during PDF/A conversion. As a consequence, applications using the SDK didn't receive these error flags, and conversion issues could go unreported. With this release, conversion event tracking is consistent across all usage paths, and XMP metadata-related errors are properly reported. - Before this update, generated API interface event handlers didn't release resources correctly. As a consequence, applications experienced increasing memory consumption over time. With this release, event handlers release resources as expected. ### Version 1.15.0 11 March 2026 #### Added - `ForbidImplicitUpgrade` option on `ConversionOptions` to prevent automatic PDF/A conformance level upgrades during conversion. #### Changed - **HEIF/HEIC codec library dynamically linked** The native library requires the HEIF/HEIC decoding library at load time, even if your application doesn't use HEIF/HEIC functionality. If the decoding library isn't found, the native library fails to load. The required binaries are included in the distribution, but ensure your service, container layout, library search paths, and permissions allow the library to be found. **Action:** After updating, verify that your deployment loads correctly even if HEIF/HEIC processing is not used. - **JBIG2 decoding update** The JBIG2 decoding implementation has been replaced. JBIG2-encoded images render identically, but error messages related to JBIG2 processing may differ from previous versions. **Action:** If you process PDFs with JBIG2-encoded images, consider validating against a representative document set. - **Updated font substitution for missing fonts (including PDF/A)** When PDFs reference fonts that aren't embedded and are unavailable on the host, the software substitutes fallback fonts. The updated fallback fonts support a larger glyph set and better fitting to original glyph dimensions. Layout should remain stable, but visual appearance differs from both the original font and previous versions. **Action:** If exact reproduction is required, install the original font in your environment. - **ZapfDingbats font delivery change** ZapfDingbats is no longer shipped. The fallback font URW++ D050000L.ttf is used instead, but it doesn't provide full coverage and may differ slightly in appearance. **Action:** If exact ZapfDingbats reproduction is required, install the font in your environment. - **Refreshed internal mapping tables** Character mapping tables used for Unicode and glyph mapping have been updated. Changes are primarily additive (new code points) with occasional correctness fixes. - **Java: native library loaded automatically** Before this release, Java applications had to explicitly locate and load the Pdftools SDK native binary using `System.load()` or `System.loadLibrary()` before calling any SDK function. With this release, the native binary is loaded automatically at runtime. The Maven dependency has also been simplified: the platform-specific native artifact classifier is no longer needed. **Action:** Remove any `System.load()` or `System.loadLibrary()` calls for the Pdftools SDK native library from your code. If you use Maven or Gradle, replace the two-dependency block (main JAR + native artifact) with a single dependency on `pdftools-sdk`. If you manage JARs manually, ensure both [`pdftools-sdk`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk/) and [`pdftools-sdk-native`](https://repo1.maven.org/maven2/com/pdftools/pdftools-sdk-native/) JARs are on your classpath, and remove any native binaries (`.dll`, `.so`, `.dylib`) you previously placed in your project. Refer to the [Java getting started guide](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java) for the updated configuration. - Upgraded libxml2 from version 2.10.3 to 2.15.0. Error messages related to XML processing may differ from previous versions. #### Fixed - Debug-level log messages are written to the file output sink when file logging is configured via `PDF_TRACE_OUTPUT` or `PDFT_LOG_OUTPUT`. - Fixed a crash when repairing PDFs with XMP metadata dates missing timezone information. - PDF/A conversion no longer fails when the document contains a `/Tabs` entry written as a string instead of a name object. - PDF/A conversion no longer fails when the document contains a CIDFont dictionary without a `/Type` entry. - The remove-PieceInfo option (`eStripPieceInfo`) also removes PieceInfo dictionaries from XObject resources. - Before this update, on Linux, PDF dates were computed using the UTC offset of the current time instead of the UTC offset applicable to the date being processed. As a consequence, PDF dates could be off by one hour when the document's date and the current time fell in different daylight saving time (DST) periods. With this release, the UTC offset is correctly derived from the date being processed. - Before this update, the JBIG2 decoder placed no limit on memory allocations, which could cause excessive memory consumption when processing PDFs with malformed or unusually large JBIG2-encoded images. With this release, JBIG2 memory allocation is capped at 2 GB. - Before this update, calling `Extractor.ExtractText()` using the C# binding on Linux produced incorrect output. As a consequence, non-ASCII UTF-8 characters were silently dropped from the extracted text. With this release, text extraction produces correct UTF-8 output on Linux. ### Version 1.14.0 29 October 2025 #### Added - Enhanced logging configuration environment variables: - `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility. - `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level. #### Changed - Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions. #### Fixed - Corrected conformance retrieval logic in the `GetConformance` method to properly handle invalid `ConversionOptions` values. - Certificate loading on Windows now includes Local Machine store in addition to Current User store, resolving certificate access issues for Internet Information Services (IIS) applications running under service accounts. - Widget annotation appearance generation now correctly checks for rich text value (RV) entry instead of rich text style (DS) entry when determining whether to create appearance streams. ### Version 1.13.1 16 September 2025 #### Fixed - Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing. - Fixed a stack buffer overflow when creating annotation appearances. - Corrected glyph position problems caused by improper handling of adjustment values. - Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files. - Fixed an infinite loop that could occur during optimization for specific malformed PDF files. - Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes. ### Version 1.13.0 29 July 2025 #### Added - Added `IsFullRevisionCovered` flag to signature validation results to detect partial `ByteRanges`. #### Changed - Removed library load/unload messages from Python bindings. #### Fixed - Font name decoding for Type0 fonts on Linux and macOS to preserve Unicode characters. - Malformed import in `native_base.py` that caused errors in Python bindings. - Fixed error reporting for non-UTF8 colorant name on Linux and macOS. - Font name decoding on Linux and macOS to align behavior with Windows. - Fixed unexpected termination when processing image dictionaries with an empty `/Filter` array. - Removed stray null terminators from strings returned by the Python interface. ### Version 1.12.0 19 June 2025 #### Added - The Pdftools SDK now natively supports Linux ARM64 processor architecture. #### Fixed - Previously, soft mask dimensions were not properly validated when a matte background was present. ### Version 1.11.1 26 May 2025 #### Fixed - Resolved an issue that could cause a crash during rendering of Type 1 shadings. - Addressed a problem with native library shutdown procedures that led to crashes or hangs when used through language bindings. - Corrected the internal mapping for the `WordSeparationFactor` option, which previously could result in incorrect text extraction configuration. ### Version 1.11.0 16 May 2025 #### Added - Improved multi-threaded handling of shared read-only data structures, allowing read-only configuration data to be shared safely between threads. #### Fixed - Resolved a crash that occurred when merging PDF files containing form fields without appearance streams while flattening was enabled. ### Version 1.10.0 12 May 2025 #### Added - As of this update, you can now extract text from PDFs by using the Pdftools SDK. Review the following API references for more information: [C](https://api-reference.pdf-tools.com/pdfsdk/1.10/cdoc/_pdf_tools___pdf_tools_extraction_8h.html), [Java](https://api-reference.pdf-tools.com/pdfsdk/1.10/javadoc/com/pdftools/extraction/package-summary.html), [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.10/dotnet/html/N_PdfTools_Extraction.htm), and [Python](https://api-reference.pdf-tools.com/pdfsdk/1.10/pydocs/_autosummary/pdftools_sdk.extraction.html#module-pdftools_sdk.extraction). - Code examples now include links to Jupyter notebooks marked as the **Open in Colab** buttons. For more details, review [the Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples). ### Version 1.9.1 14 April 2025 #### Added - With this release, we are launching a new [Python Jupyter notebooks repository](https://github.com/pdf-tools/components-code-sample-hub) demonstrating the core functionality of the Pdftools SDK, including step-by-step examples for key features and use cases. #### Fixed - Previously, rendering PDFs with the wrong alternate colorspaces could cause the Pdftools SDK to crash. With this update, the rendering engine now falls back to CMYK rendering if the alternate color transform cannot be created, preventing the crash. - Prior to this update, a crash occurred when IIS processes terminated, causing the Pdftools SDK DLL to unload without properly releasing its resources. With this release, the issue has been resolved, allowing the DLL to safely unload even when shutdown hooks fail to execute as expected. - Previously, document timestamps (ETSI.RFC3161) were not recognized if the PDF lacked an explicit declaration of the correct signature type. This update ensures that timestamps are correctly validated as long as the signature itself is valid and the signed content remains intact. ### Version 1.9.0 14 March 2025 #### Added - Improved support for HEIC files. #### Fixed - Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release. - Fixed a bug that caused crashes when handling JPEG images with the Pdftools SDK on 32-bit Windows systems. - Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps. ### Version 1.8.0 20 January 2025 #### Added - The Pdftools SDK now natively supports Microsoft Windows ARM64 processor architecture. - During PDF/A conversion, you can now add embed associated files using the [AddAssociatedFile](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddAssociatedFile.htm) method. - Test whether any update leading to a specific revision does not contain a digital signature using the new [HasNonSigningUpdates](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Pdf_Revision_HasNonSigningUpdates.htm) property. - Suppress rendering of text when converting a PDF to an image using the new [RenderText](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Pdf2Image_ContentOptions_RenderText.htm) property. - With this update, you can force an image to fill the page (respecting the image's aspect ratio) using the [ForceFit](https://api-reference.pdf-tools.com/pdfsdk/1.8/dotnet/html/P_PdfTools_Image2Pdf_ShrinkToFit_ForceFit.htm) property. - With this update, the Pdftools SDK introduces a new Pythonic, object-oriented interface with structured classes, native Python types for data handling, and enhanced error management through exceptions. For more details on how to try the new Pythonic interface, review [Python getting started guide](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python). #### Fixed - Missing `firstChar` or `lastChar` entries in damaged font dictionaries are restored when enough information is available. - Fixed issue for PDFs with signed signature fields without any appearance. - There was an issue when the SDK tried to get resources by HTTPS in the visual appearance of JSON or XML configuration files. The issue was fixed with this update. ### Version 1.7.0 28 June 2024 #### Added - The Pdftools SDK now lets you adjust the image quality using the [ImageQuality](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/P_PdfTools_PdfA_Conversion_ConversionOptions_ImageQuality.htm) property when converting a PDF file to PDF/A. This setting is used when images must be recompressed during the conversion process. - You can now use **pip** package manager to install the Pdftools SDK. Use `pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/pdftools_sdk-latest.tar.gz` to install the Python version of the Pdftools SDK from our servers. #### Fixed - Corrected an issue where Unicode characters were sometimes converted incorrectly when using the [Python version of the Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python). - Fixed a bug where some ZUGFeRD v3 invoice XML files were not correctly recognized by the [AddInvoiceXml](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddInvoiceXml.htm) method when creating a ZUGFeRD invoice. ### Version 1.6.0 31 May 2024 #### Added - You can now create a fully compliant ZUGFeRD or Factur-X invoice using the Pdftools SDK. To do this you [add the invoice XML file](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddInvoiceXml.htm) before calling the [Convert](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_Convert.htm) method. - It is now possible to [rotate a page](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/P_PdfTools_DocumentAssembly_PageCopyOptions_PageRotation.htm) when merging pages of PDF documents using the [Assemble](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/T_PdfTools_DocumentAssembly_DocumentAssembler.htm) method. - Instead of using the default [Font directories](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/general-notes#font-directories), you can now also add a custom font directory using the [AddFontDirectory](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_Sdk_AddFontDirectory.htm) method. #### Fixed - Previously, a default value was always used for the PDF Producer value. With this update, the issue was fixed, and the PDF Producer value is now set correctly using the `producerSuffix` parameter of the [`Initialize(licenseKey, producerSuffix)`](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/M_PdfTools_Sdk_Initialize.htm) method. - The validation of a digital signature's [Appearance](https://api-reference.pdf-tools.com/pdfsdk/1.6/dotnet/html/Properties_T_PdfTools_Sign_Appearance.htm) has been improved, to prevent inconsistent boundary values. ### Version 1.5.0 17 April 2024 #### Added - You can now apply [Mixed Raster Content (MRC)](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/T_PdfTools_Optimization_Profiles_Mrc.htm) optimization to a PDF document using the [Optimize](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimize-a-pdf) feature of the Pdftools SDK. MRC optimization is intended for compressing scanned PDF files that contain large amounts of text. - It is now possible to set the values for [ThresholdDPI](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/P_PdfTools_Optimization_Profiles_Web_ThresholdDPI.htm) and [ReduceColorComplexity](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/P_PdfTools_Optimization_ImageRecompressionOptions_ReduceColorComplexity.htm) when optimizing PDF files. This addition gives you more control over how images in the document are resampled and compressed. #### Changed - The [OptimizeDocument](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/M_PdfTools_Optimization_Optimizer_OptimizeDocument.htm) method of the PDF optimizer will now attempt to apply lossless compression for images with bitonal (Group4 or JBIG2 compression) and indexed (Flate or LZW compression) color spaces. ### Version 1.4.0 5 March 2024 #### Added - Before this update, only the common name (CN) of a signing certificate could be retrieved. With this update, you can get the full [distinguished name](https://api-reference.pdf-tools.com/pdfsdk/1.4/dotnet/html/P_PdfTools_SignatureValidation_Certificate_Subject.htm) (DN) of a signing certificate. The DN format is RFC 4514. The DN includes the legal name, country, and other information about the person or authority who owns the certificate. - Before this update, you could only read and write to file streams with the C API. As of this update, you can also use [memory streams](https://api-reference.pdf-tools.com/pdfsdk/1.4/cdoc/_pdf_tools___pdf_tools_sys_8h.html#add0ac122cf14ff02342a4f2b13fdcd5a) with the C API. ### Version 1.3.0 13 October 2023 #### Added - [DocumentAssembler](https://api-reference.pdf-tools.com/pdfsdk/1.3/dotnet/html/T_PdfTools_DocumentAssembly_DocumentAssembler.htm) class. This class allows you to combine multiple input PDF documents into one output document, or split one input PDF document into multiple output documents. - You can now include a customizable signature appearance when [Signing a PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-document). A signature's appearance may be any combination of text, images, and other PDF documents. - **Linux**: Added new distribution for older Linux systems (glibc 2.12+). #### Changed - Before version 1.3.3 you needed to use an evaluation license key to try the Pdftools SDK. With version 1.3.3, you can use the Pdftools SDK without a license key with watermarked output files. As a result, you can try the Pdftools SDK without any license key. To remove the watermark from the output files, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license. ### Version 1.2.0 25 August 2023 - Added the [MetadataSettings](https://api-reference.pdf-tools.com/pdfsdk/1.2/dotnet/html/T_PdfTools_Pdf_MetadataSettings.htm) class. This class allows you to set Metadata in the output PDF document, by providing them in the producer method's [OutputOptions](https://api-reference.pdf-tools.com/pdfsdk/1.2/dotnet/html/T_PdfTools_Pdf_OutputOptions.htm). #### Changed - **Linux**: The minimum required glibc version was upgraded from 2.27 to 2.34. ### Version 1.1.0 31 May 2023 #### Added - Signature validation for the [digital signing](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/) functionality. This allows you to extract signing certificate information and trust chain information, and perform validation of time-stamps, handle expired certificates, use custom trust stores, and check for the latest document revision. #### Changed - **Updated C API ZIP archive layout**: The C API ZIP archive directory layout has been updated. - **Updated Java API ZIP archive layout**: The Java API ZIP archive directory layout has been updated. ## Pdftools SDK Shell Tool ### Version 1.12.0 24 April 2026 #### Added - **`ocr` command for making PDFs searchable** The new `ocr` command applies OCR to a PDF from the command line. It connects to a [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) instance, recognizes text in scanned images, fixes non-extractable text, and can add accessibility tagging. Example: `pdf in.pdf ocr -ocr service -oim updateText out.pdf`. For full options and examples, refer to [OCR a PDF with the Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-with-shell-tool). - **`-lgs` option for the Licensing Gateway Service endpoint** If you use a page-credit license key, you can configure the Licensing Gateway Service (LGS) endpoint directly from the command line using `-lgs `. The URL accepts the form `(http|https)://[user[:password]@]host[:port]`. When you don’t specify the option, Pdftools SDK Shell Tool uses the default licensing endpoint. - **`-d` option for dithering control in Fax image conversion** The Fax conversion profile exposes a dithering option, letting you switch between `Halftone` (default), `None`, `FloydSteinberg`, and `Atkinson` when rendering PDFs to fax-ready images. For more details, refer to [Fax conversion profile](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/conversion-profiles#fax). #### Fixed - Before this update, generated API interface event handlers didn't release resources correctly. As a consequence, applications experienced increasing memory consumption over time. With this update, event handlers release resources as expected. - Before this release, optimizing PDFs with certain internal structures caused the optimizer to perform many redundant object comparisons. As a consequence, optimization appeared to hang and didn't complete on the affected documents. With this release, the optimizer avoids the redundant comparisons. As a result, optimization finishes in the expected time on the affected documents. - Prior to this update, PDF/A conversion incorrectly reported a device-color-space error on documents containing nested form XObjects. As a consequence, valid documents couldn't be converted to PDF/A. With this update, the converter resolves color spaces correctly. As a result, these documents convert to PDF/A as expected. - Before this update, validating a malformed PDF containing nested object streams caused caused unbounded recursion. As a consequence, the `validate` command crashed with a stack overflow on the affected documents. With this release, the validator detects the cycle and rejects the document with a clean validation error. As a result, malformed input can no longer crash the validator. ### Version 1.11.0 11 March 2026 #### Changed - **HEIF/HEIC codec library dynamically linked** The native library requires the HEIF/HEIC decoding library at load time, even if your application doesn't use HEIF/HEIC functionality. If the decoding library isn't found, the native library fails to load. The required binaries are included in the distribution, but ensure your service, container layout, library search paths, and permissions allow the library to be found. **Action:** After updating, verify that your deployment loads correctly even if HEIF/HEIC processing is not used. - **JBIG2 decoding update** The JBIG2 decoding implementation has been replaced. JBIG2-encoded images render identically, but error messages related to JBIG2 processing may differ from previous versions. **Action:** If you process PDFs with JBIG2-encoded images, consider validating against a representative document set. - **Updated font substitution for missing fonts (including PDF/A)** When PDFs reference fonts that aren't embedded and are unavailable on the host, the software substitutes fallback fonts. The updated fallback fonts support a larger glyph set and better fitting to original glyph dimensions. Layout should remain stable, but visual appearance differs from both the original font and previous versions. **Action:** If exact reproduction is required, install the original font in your environment. - **ZapfDingbats font delivery change** ZapfDingbats is no longer shipped. The fallback font URW++ D050000L.ttf is used instead, but it doesn't provide full coverage and may differ slightly in appearance. **Action:** If exact ZapfDingbats reproduction is required, install the font in your environment. - **Refreshed internal mapping tables** Character mapping tables used for Unicode and glyph mapping have been updated. Changes are primarily additive (new code points) with occasional correctness fixes. - Updated to .NET 10. #### Fixed - Debug-level log messages are written to the file output sink when file logging is configured via `PDF_TRACE_OUTPUT` or `PDFT_LOG_OUTPUT`. - Fixed a crash when repairing PDFs with XMP metadata dates missing timezone information. - PDF/A conversion no longer fails when the document contains a `/Tabs` entry written as a string instead of a name object. - PDF/A conversion no longer fails when the document contains a CIDFont dictionary without a `/Type` entry. - The `-rpi` option also removes PieceInfo dictionaries from XObject resources. - Before this update, on Linux, PDF dates were computed using the UTC offset of the current time instead of the UTC offset applicable to the date being processed. As a consequence, PDF dates could be off by one hour when the document's date and the current time fell in different daylight saving time (DST) periods. With this release, the UTC offset is correctly derived from the date being processed. - Before this update, the JBIG2 decoder placed no limit on memory allocations, which could cause excessive memory consumption when processing PDFs with malformed or unusually large JBIG2-encoded images. With this release, JBIG2 memory allocation is capped at 2 GB. - Before this update, extracting text from PDFs on Linux produced incorrect output. As a consequence, non-ASCII UTF-8 characters were silently dropped. With this release, text extraction produces correct UTF-8 output on Linux. ### Version 1.10.0 29 October 2025 #### Added - Enhanced logging configuration environment variables: - `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility. - `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level. #### Changed - Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions. #### Fixed - Correct the usage text for the render-archive operation as there is no `-max` option in the general options. - Corrected conformance retrieval logic in the `GetConformance` method to properly handle invalid `ConversionOptions` values. - Certificate loading on Windows now includes Local Machine store in addition to Current User store, resolving certificate access issues for Internet Information Services (IIS) applications running under service accounts. ### Version 1.9.1 16 September 2025 #### Fixed - Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing. - Fixed a stack buffer overflow when creating annotation appearances. - Corrected glyph position problems caused by improper handling of adjustment values. - Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files. - Fixed an infinite loop that could occur during optimization for specific malformed PDF files. - Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes. ### Version 1.9.0 29 July 2025 #### Fixed - Fixed blank pages caused by incorrect indirect color space references in inline images. - Fixed unexpected termination when handling image dictionaries with empty `/Filter` array. ### Version 1.8.0 19 June 2025 #### Added - As of this update, you can extract text from PDFs using the following commands: - `text-extract`: Recommended for LLM ingestion. Extracts text in the order it appears in the PDF. - `layout-text-extract`: Extract text by mimicking the layout of the PDF. - The Pdftools SDK Shell Tool now natively supports Linux ARM64 processor architecture. #### Fixed - Previously, soft mask dimensions were not properly validated when a matte background was present. - Corrected handling of the `fit` keyword in alternate text validation. ### Version 1.7.0 23 April 2025 #### Added - Add the support to embedding files during a PDF/A conversion: embedding files can be associated to the converted PDF - Add fit page option to the import image functionality: all images will be scaled to fit the page size (including enlarging smaller images). - Improved support for HEIC files. #### Fixed - Fixed a bug that caused crashes when handling JPEG images with the Pdftools SDK on 32-bit Windows systems. - Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps. - Previously, document timestamps (ETSI.RFC3161) were not recognized if the PDF lacked an explicit declaration of the correct signature type. This update ensures that timestamps are correctly validated as long as the signature itself is valid and the signed content remains intact. - Previously, rendering PDFs with the wrong alternate colorspaces could cause the Pdftools SDK to crash. With this update, the rendering engine now falls back to CMYK rendering if the alternate color transform cannot be created, preventing the crash. - Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release. ### Version 1.6.0 10 January 2025 #### Added - Add a new method `AddAssociatedFile` that lets you to embed a file into a PDF. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdk/1.10/cdoc/_pdf_tools___pdf_tools_pdf_a_conversion_8h.html#ab674762cd56eda03c2ed78332e94c343), [Java](https://api-reference.pdf-tools.com/pdfsdk/1.10/javadoc/com/pdftools/pdfa/conversion/Converter.html#addAssociatedFile(com.pdftools.sys.Stream,java.lang.String,java.lang.Integer,com.pdftools.pdfa.conversion.AFRelationship,java.lang.String,java.lang.String,java.time.OffsetDateTime)), [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.10/dotnet/html/M_PdfTools_PdfA_Conversion_Converter_AddAssociatedFile.htm), [Python](https://api-reference.pdf-tools.com/pdfsdk/1.10/pydocs/_autosummary/pdftools_sdk.pdf_a.conversion.converter.html#pdftools_sdk.pdf_a.conversion.converter.Converter.add_associated_file). - The Pdftools SDK Shell Tool now natively supports Microsoft Windows ARM64 processor architecture. #### Fixed - Add ability to get a license key from a default location when none is provided. The usage help message will display the alternative locations of the license (file or env. variable) - Corrected encoding of console text output. - Shell tool version couldn’t be fetched from the executable and properly display in usage help message. - Missing firstChar or lastChar entries in damaged font dictionaries are restored when enough information is available. - Fixed issue for PDFs with signed signature fields without any appearance. - There was an issue when the SDK tried to get resources by HTTPS in the visual appearance of JSON or XML configuration files. The issue was fixed with this update. - Fixed a bug where some ZUGFeRD v3 invoice XML files were not correctly recognized by the AddInvoiceXml method when creating a ZUGFeRD invoice. ### Version 1.5.0 28 June 2024 #### Added - You can now pass an optional `-q ` parameter to the `convert` command in the Pdftools SDK Shell Tool, to set the image quality using the [ImageQuality](https://api-reference.pdf-tools.com/pdfsdk/1.7/dotnet/html/P_PdfTools_PdfA_Conversion_ConversionOptions_ImageQuality.htm) property when converting a PDF file to PDF/A. This setting is used when images must be recompressed during the PDF/A conversion process. ### Version 1.4.0 10 June 2024 #### Added - Support for converting a PDF document and an XML file to a PDF/A invoice in ZUGFeRD or Factur-X format. You can now pass an optional `-xml ` parameter to the `convert` command of the Pdftools SDK Shell Tool to embed the specified XML file and create the invoice. - You can now rotate a page when copying it from one PDF to another. Pass the optional `-rot ` parameter to the `merge` command to rotate a set of pages by the specified value (`90`, `180`, or `270` degrees) before adding them to the output file. - Support for [digital signature](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/) functionality using the Pdftools SDK Shell Tool. You can now sign, certify, and timestamp PDF files. You can also add and list signature fields, and check the validity of the digital signatures in a PDF document. ### Version 1.3.0 25 April 2024 #### Added - Support for [mixed raster content](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimization-profiles#mixed-raster-content-optimization-profile) (MRC) optimization. You can now use the mixed raster content optimization profile by using the `optimize-mrc` command with the Pdftools SDK Shell Tool. - You can now enable or disable the [reduce color complexity](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/optimization-profiles#mixed-raster-content-optimization-profile) by using the `-drc` option when performing PDF optimization. ### Version 1.2.0 12 April 2024 #### Added - Support PDF to PDF/A file conversion. All supported PDF and PDF/A versions are listed in [Supported PDF versions](https://www.pdf-tools.com/docs/pdf-tools-sdk/technical-specifications#supported-pdf-versions). - Support PDF file validation of conformance with PDF or PDF/A standards listed in [Supported PDF versions](https://www.pdf-tools.com/docs/pdf-tools-sdk/technical-specifications#supported-pdf-versions). - Before version 1.2 the Pdftools SDK Shell Tool was only available as a framework-dependent .NET application. Now you can also download the Pdftools SDK Shell Tool as a self-contained application for Windows, Mac, and Linux. ### Version 1.1.0 19 January 2024 #### Added - Support for merging and splitting PDF files to assemble new output documents. - Support for rendering PDF files to an image suitable for fax, archiving, or viewing. ### Version 1.0.0 22 September 2023 #### Added - Support for converting images to PDF or PDF/A files - Support compression and optimization of PDF files for web, archive, or print to minimize the file size. --- ## Pdftools SDK technical specifications The Pdftools SDK provides a comprehensive development library for C, C#, Java, and Python with advanced PDF capabilities. ## Functionality The following list provides an overview of the core functionality of the Pdftools SDK with links to specific implementation guides: - [Archive PDFs to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/#archive-pdf-to-pdfa): Archive documents to PDF/A standards. - [Compress and optimize PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/): Compress and optimize PDF files. - [Convert images to PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/#convert-images-to-pdf): Convert various image formats to PDFs. - [Convert PDFs to images](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/#convert-pdfs-to-images): Convert PDFs to image formats. - [Embed e-invoice as ZUGFeRD or Factur-X](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/e-invoice/): Add ZUGFeRD or Factur-X invoices. - [Merge and split PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/assemble/): Assemble documents, merge, split, and extract PDF content. - [Sign and certify PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/): Sign and certify documents. - [Secure and encrypt PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/): Secure and encrypt documents. - [Validate PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/): Validate PDF conformance against many specification types. ## Trial license You can use the same license key for the Pdftools SDK, the Pdftools SDK Shell Tool, and the Toolbox add-on. The Pdftools SDK and the Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. ## Supported languages and frameworks The Pdftools SDK is available for the following languages: | Language or framework | Minimal supported version | Getting started | |-----------------------|--------------------------------------------------------|------------------------------------------------------------------------| | C | GCC toolset 4.8+, CMake 3.16+ | [C](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-c) | | Java | Java 8+ | [Java](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java) | | .NET | .NET/.NET Core 2.0+ or .NET Framework 4.6.1+ | [.NET](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-dotnet) | | Python | Python 3.6+ | [Python](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python) | | Other languages (Go) | Go 1.6+ | [Other languages](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-other-languages) | ## Supported operating systems The Pdftools SDK is available for multiple operating systems: | Operating system | Supported architecture and other dependencies | |---------------------------------------------------|----------------------------------------------------------------------| | Windows Client 7+ | x86 or x64 | | Windows Server 2008+ | x86 or x64 | | macOS 10.10+ | x64 or arm64 | | Linux (RHEL 6.9+, CentOS 6+, Oracle Linux 8+, Fedora 29+, Debian 10+, Ubuntu 22.04+) | x64 | | Other Linux distribution (glibc 2.34+) | Linux kernel 2.6+, GCC toolset 4.8+, glibc 2.34+, x64 | | Other Linux distribution (glibc 2.12+) | Linux kernel 2.6+, GCC toolset 4.1+, glibc 2.12+, x64 | ## Supported PDF versions The Pdftools SDK supports the following PDF versions: | Version | Standard | | ------------ | ------------------------------------------------------ | | PDF 1.x | PDF Reference 1.3 - 1.6 | | PDF 1.7 | PDF 1.7 / ISO 32000-1 | | PDF 2.0 | PDF 2.0 / ISO 32000-2 | | PDF/A-1a | PDF/A-1a / ISO 19005-1 / Level A conformance | | PDF/A-1b | PDF/A-1b / ISO 19005-1 / Level B conformance | | PDF/A-2a | PDF/A-2a / ISO 19005-2 / Level A conformance | | PDF/A-2b | PDF/A-2b / ISO 19005-2 / Level B conformance | | PDF/A-2u | PDF/A-2u / ISO 19005-2 / Level U conformance | | PDF/A-3a | PDF/A-3a / ISO 19005-3 / Level A conformance | | PDF/A-3b | PDF/A-3b / ISO 19005-3 / Level B conformance | | PDF/A-3u | PDF/A-3u / ISO 19005-3 / Level U conformance | ## Supported image file formats The Pdftools SDK supports the following image file formats: - JPEG - JPEG2000 - JBIG2 - PNG - GIF - TIFF - HEIC/HEIF :::tip[Get started] Try the SDKs with one of the **[Getting started guides](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/)**. --- ## PDF Viewer SDK Integrate a comprehensive PDF viewer with editing capabilities into web applications. The PDF Viewer SDK is a TypeScript and JavaScript development library designed to work across multiple browsers. It also supports integration with libraries like React and frameworks such as Angular. ## Functionality With the PDF Viewer SDK, you can work with PDFs directly on the client, without the need for a server-side PDF library. The PDF Viewer SDK provides the following functionality: ### Viewing - Render PDF documents with high fidelity. - Navigate pages. - Zoom and scroll through documents. - Configure fit mode and page layout mode. ### Search - Search text within documents. - Highlight and navigate search results. ### Annotations - Add, edit, and delete annotations. - Supported types: highlight, underline, strikeout, squiggly, sticky notes, free text, shapes, lines, stamps, and images. ### Document operations - Open documents from URL, file, or memory. - Save documents with or without changes. - Download and print documents. - Access document metadata and page information. ### Customization - Build custom plugins for extended functionality. - Customize buttons and their behaviors. - Listen to and dispatch events programmatically. ## Packaging The PDF Viewer SDK consists of two npm packages, the PDF Web Viewer and the PDF Web SDK: - [PDF Web Viewer](#pdf-web-viewer) - [PDF Web SDK](#pdf-web-sdk) ### PDF Web Viewer The [PDF Web Viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) is a ready-to-use, customizable viewer component featuring a complete user interface, including a toolbar, sidebar, and all standard PDF viewing and editing features. Customize the appearance with CSS, extend functionality with custom plugins, and integrate with your application through events. Use this package when you want to quickly integrate a full-featured PDF viewer into your application. :::tip[Get started] Try it out with **[Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/)**. ### PDF Web SDK The [PDF Web SDK](https://www.npmjs.com/package/@pdftools/pdf-web-sdk) provides a document view and the core rendering and document manipulation capabilities. Use this package when you need to build a completely custom viewer with your own interface. :::tip[Learn about advanced functionality] Implement more complex use cases or build your own custom viewer using the advanced functionality of the PDF Web SDK. For more information, review **[advanced functionality](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/)**. ## License overview The following table explains the pricing and feature offering available for various license types of the PDF Viewer SDK: No license Free view-only Trial Professional Business Enterprise How to No license key is need Contact sales Contact sales Contact sales Contact sales Contact sales Watermark Yes No No No No No Feature sets View-only View-only All Select one Select three All Domains - One On demand One Three On demand Maximum concurrent users 100 100 extensible 100 extensible 100 extensible 1,000 extensible Contract based ## Supported programming languages and frameworks The PDF Viewer SDK is provided as a TypeScript and JavaScript library. It can be used in applications built with libraries like React and frameworks such as Angular. ## Supported browsers The PDF Viewer SDK is tested with and supported for the following browsers: - Chrome 63+ - Edge 41+ - Firefox 55+ - Safari 11.0.3+ ## Supported PDF versions The PDF Viewer SDK supports the following PDF versions: | Version | Standard | | ------------ | ------------------------------------------------------ | | PDF 1.x | PDF Reference 1.3 - 1.6 | | PDF 1.7 | PDF 1.7 / ISO 32000-1 | | PDF 2.0 | PDF 2.0 / ISO 32000-2 | | PDF/A-1a | PDF/A-1a / ISO 19005-1 / Level A conformance | | PDF/A-1b | PDF/A-1b / ISO 19005-1 / Level B conformance | | PDF/A-2a | PDF/A-2a / ISO 19005-2 / Level A conformance | | PDF/A-2b | PDF/A-2b / ISO 19005-2 / Level B conformance | | PDF/A-2u | PDF/A-2u / ISO 19005-2 / Level U conformance | | PDF/A-3a | PDF/A-3a / ISO 19005-3 / Level A conformance | | PDF/A-3b | PDF/A-3b / ISO 19005-3 / Level B conformance | | PDF/A-3u | PDF/A-3u / ISO 19005-3 / Level U conformance | | FDF | included in above standards | **note: When saving changes, the PDF Viewer SDK saves the document in the same PDF version as the original file you opened. ** To convert documents between PDF versions, please use the: - [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) - [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) --- ## PDF Viewer SDK architecture The PDF Viewer SDK architecture consists of two interconnected npm packages, where the top package builds upon the functionality of the base package. The top package is the PDF Web Viewer package, which provides core viewer capabilities for rendering and interacting with PDF documents. At the base level is the PDF Web SDK package, which provides the necessary functionality for the PDF Web Viewer package. It also includes additional APIs and advanced features, offering a comprehensive toolkit for viewing and working with PDFs that you can implement into your application. However, PDF Viewer SDK is a ready-to-use package, while implementing the PDF Web SDK requires significant development effort compared to the full PDF Viewer SDK. | Layer | Name | npm package | API reference | | ----: | ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------- | | 1 | [PDF Web Viewer](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-viewer) | [@pdftools/pdf-web-viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) | [Viewer API reference](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/) | | 2 | [PDF Web SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-sdk) | [@pdftools/pdf-web-sdk](https://www.npmjs.com/package/@pdftools/pdf-web-sdk) | [PDF Web SDK API reference](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/) | The following chart gives an overview of the most important components in the PDF Viewer SDK and the PDF Web SDK. Refer to the following sections for more details. ## PDF Web Viewer The PDF Viewer SDK is a ready-to-use component that can easily be integrated into your application. **note: Learn how to [get started](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/).** ### PdfToolsViewer component The `PdfToolsViewer` is a class that provides a comprehensive PDF viewing experience. To use it, follow these steps: 1. Create an instance of the viewer: ```typescript const viewer = new PdfToolsViewer(); ``` 2. Initialize the class with the configuration options and a container element: ```typescript await viewer.initialize(config, containerElement); ``` The `PdfToolsViewer` component offers: - Document viewing with configurable accessibility features - Annotation capabilities (add, update, delete) with event listeners - Navigation controls (go to specific page, next/previous page) - View manipulation (rotation, zoom) - Component visibility management - Custom button behavior overrides - License-based functionality Rather than returning an element, the `PdfToolsViewer` component attaches itself to the container you provided and exposes an API for interacting with the PDF document and the viewer interface. ## PDF Web SDK The PDF Web SDK operates on a higher level of abstraction than the PDF Viewer SDK but also provides more advanced features. **note: Learn how to use the PDF Web SDK, for example to [view a document](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/document-view).** The PDF Web SDK provides several namespaces encapsulating different functionalities: ### Namespaces 1. **Core**: Core components, functionalities and utilities used by the API. 2. **Pdf**: Contains logic necessary for working with PDF files, such as opening, closing, editing, or saving PDF documents. These operations provide the foundational functionality for interacting with PDF files within the API. 1. **Annotations**: Types describing PDF annotations along with the properties related to each subtype. 2. **Drawing**: Types related to drawing or rendering PDF content, such as drawing shapes, lines, or text on a PDF page. 3. **Forms**: Types related to handling PDF forms, such as filling out form fields, extracting form data, or validating form entries. 4. **Geometry**: Types related to geometric operations on PDF elements, such as calculating areas, distances, or transformations. 5. **Search**: Types related to searching for specific content within a PDF document, such as text search or advanced search capabilities. 3. **UI**: Components or functions related to building a user interface (UI) for interacting with the PDF document. ### Important components There are several components which are commonly used when interacting with a PDF document. #### PdfToolsWebSdk Singleton object named [`pdfToolsWebSdk`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/variables/pdfToolsWebSdk) is used to initialize PDF Web SDK. Singleton instance of this object is created internally and is available for public access. #### Pdf.Controller [`Pdf.Controller`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) class is used for managing documents inside the PDF Web SDK. It should be instantiated and reused for managing multiple documents. #### Pdf.Document [`Pdf.Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) class is used for representing a PDF document inside the PDF Web SDK. Instances of this object are created internally and are available for access through [`Pdf.Controller`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller). #### Pdf.Page [`Pdf.Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) class is used for representing a page inside a PDF document. Instances of this object are created internally and are available for access through [`Pdf.Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) property called `pages`. #### Pdf.AnnotationManager [`Pdf.AnnotationManager`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) class is a central interaction hub designed to handle annotation-related operations within a document. It serves as a bridge between user interactions and the underlying document structure, facilitating dynamic changes to annotations based on user actions. It's available per document through [`Pdf.Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) property called `annotations`. #### UI.DocumentView [`UI.DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) class is used for managing the presentation and interaction with a PDF document within a container element. It should be constructed with a reference to a container element and initialized with a [`Pdf.Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) in order to create an interactive preview of the PDF document. --- ## Customize the PDF Viewer SDK --- ## Getting started with the PDF Viewer SDK Get up and running with the PDF Viewer SDK. This guide walks you through the steps to integrate the [ready-to-use viewer](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-viewer) into your application. **tip: You can also follow this guide if you are starting with a project from scratch. For this, all you need is a blank folder.** ## Prerequisites To install the package, use a package manager such as npm or yarn. ## Get started with a sample project Learn how to run the PDF Viewer SDK sample: ### Compile and run the sample **info: Try the PDF Viewer SDK without a license key for free; without a license, rendered pages are watermarked.** 1. Download or clone the [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/5.15.1). 1. From the root of the repository, navigate to a sample at the following path: ``` examples/vanilla-typescript/view-pdf ``` 1. Git checkout to the branch with the latest version: ``` git checkout 5.15.1 ``` 1. Install dependencies: ``` npm install ``` 1. Build the project: ``` npm run build ``` 1. Run the server: ``` npm run dev ``` 1. Open [`http://localhost:4567/`](http://localhost:4567/) in your browser. :::tip[Run more samples] Run other samples in the same way. Review the `/examples` directory for more samples in the downloaded or cloned [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/5.15.1). ## Integrate the SDK into your application Integrate and initialize the PDF Viewer SDK into your application by following the instructions in the next sections. ### Add the SDK to your project In your project folder run the following command to install the PDF Web Viewer: ``` npm install @pdftools/pdf-web-viewer ``` ### Static assets PDF Web Viewer comes with static assets and resource files (WebAssembly and JavaScript files) stored in `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` sub-directory. To allow proper initialization of the PDF Web Viewer inside of your application, make these files publicly available to the application from a base path (for example: `/pdftools-web-viewer`). You can do this automatically or manually depending on your system, see the following sections for more details: - [Copy static assets automatically](#copy-static-assets-automatically) - [Copy static assets manually](#copy-static-assets-manually) #### Copy static assets automatically Automate the process for development and production using a bundler, to make sure that always the proper assets are used on every build. While copying files manually for prototyping is a viable way, automating this process is recommended. **React:** In React, tools like **Webpack** or **Rollup** are typically used for bundling your application. **Webpack:** Automate copying of the assets and resource files using `copy-webpack-plugin`. This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build. An example of `webpack.config.js`: ```javascript const CopyWebpackPlugin = require("copy-webpack-plugin"); module.exports = { // Other Webpack configuration options... plugins: [ new CopyWebpackPlugin({ patterns: [ { from: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", to: "pdftools-web-viewer", }, ], }), ], }; ``` For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin). **Rollup:** Automate the copying of assets and resource files using `rollup-plugin-copy`. This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build. An example of `rollup.config.js`: ```javascript import copy from "rollup-plugin-copy"; export default { // Other Rollup configuration options... plugins: [ copy({ targets: [ { src: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", dest: "pdftools-web-viewer", }, ], }), ], }; ``` For more details see [official rollup-plugin-copy documentation](https://www.npmjs.com/package/rollup-plugin-copy). **Angular:** Add the path to the static assets in the assets array of your `angular.json` file. ```json "assets": [ "src/favicon.ico", "src/assets", { "glob": "**/*", "input": "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", "output": "/pdftools-web-viewer/" } ] ``` For more details, review [official Angular documentation](https://angular.io/guide/workspace-config#asset-config). **Vue:** In Vue, **Webpack** is typically used for bundling your application. **Webpack:** Copying of the assets and resource files can be automated using `copy-webpack-plugin`. This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build. An example of `webpack.config.js`: ```javascript const CopyWebpackPlugin = require("copy-webpack-plugin"); module.exports = { // Other Webpack configuration options... plugins: [ new CopyWebpackPlugin({ patterns: [ { from: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", to: "pdftools-web-viewer", }, ], }), ], }; ``` For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin). For details also see [official Vue CLI Webpack configuration documentation](https://cli.vuejs.org/guide/webpack.html#simple-configuration). **Vanilla TypeScript:** Tools like **Webpack** or **Rollup** can be used for bundling your application. **Webpack:** Copying of the assets and resource files can be automated using `copy-webpack-plugin`. This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build. An example of `webpack.config.js`: ```javascript const CopyWebpackPlugin = require("copy-webpack-plugin"); module.exports = { // Other Webpack configuration options... plugins: [ new CopyWebpackPlugin({ patterns: [ { from: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", to: "pdftools-web-viewer", }, ], }), ], }; ``` For more details see [official copy-webpack-plugin documentation](https://webpack.js.org/plugins/copy-webpack-plugin). **Rollup:** Copying of the assets and resource files can be automated using `rollup-plugin-copy`. This automatically copies the files from `node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer` to `/pdftools-web-viewer` on every build. An example of `rollup.config.js`: ```javascript import copy from "rollup-plugin-copy"; export default { // Other Rollup configuration options... plugins: [ copy({ targets: [ { src: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer", dest: "pdftools-web-viewer", }, ], }), ], }; ``` For more details see [official rollup-plugin-copy documentation](https://www.npmjs.com/package/rollup-plugin-copy). :::info[Copy files differently in PDF Web SDK] In case you are using just the [PDF Web SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-sdk) without the [PDF Web Viewer](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-viewer) in your project: 1. Copy static assets from `node_modules/@pdftools/pdf-web-sdk/pdftools-web-sdk`. #### Copy static assets manually Copy the static assets manually if you have specific requirements within your project that can be difficult to solve with automatic copy by issuing the following steps: 1. Copy the files to a publicly available path. 2. If your project is served through a server, ensure that the server is configured to serve WASM files with the appropriate MIME type (application/wasm). ### Initialize the viewer When you are finished with the resources setup, initialize the PDF Viewer SDK with the following steps: 1. Create a minimalistic HTML page (for example `index.html`) with a `` element, including a Viewer container. Review the example below: ```html Document {/* this element will be used to attach the viewer to it */} ``` 1. Create a short TypeScript file that performs the initialization of the PDF Viewer SDK: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { // create the viewer instance const viewer = new PdfToolsViewer(); // attach it to the container element const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({}, container); } initialize(); ``` **note: By default the PDF Web Viewer looks for static assets in `'./pdftools-web-viewer/'`.** If you configure your project's [static assets](#static-assets) in a different location, provide the location as an argument: ```typescript const viewer = new PdfToolsViewer(); await viewer.initialize( { path: "./pdftools-web-viewer/", }, container ); ``` ### Manage license key The PDF Viewer SDK displays watermarked pages by default without a license key. Use a trial or production license key to remove the watermark. To obtain the license key: 1. Contact sales through the [contact form](https://www.pdf-tools.com/contact/) to obtain the Free View-only license. When you obtain the license key, include it in the initialize method to remove the watermark. 1. Search for the `viewer.initialize` method call in the `index.ts` or `index.js`, and include the license key as follows: ```ts const viewer = new PdfToolsViewer(); await viewer.initialize( { licenseKey: "", }, container ); ``` ### Open a PDF document With the ready-to-use viewer, end users can open files using a built-in file-open dialog. Optionally the file can be opened programmatically from different sources: **From URL:** ```typescript // open a document from a URL viewer.file.emitOpened({ uri: "../pdf/WebViewer_Demo.pdf" }); ``` **From file:** ```typescript // load the document content from an arbitrary source const res = await fetch("http://localhost:3300/pdf/WebViewer_Demo.pdf"); const arrayBuffer = await res.arrayBuffer(); // convert the content to BLOB const base64 = btoa( new Uint8Array(arrayBuffer).reduce( (data, byte) => data + String.fromCharCode(byte), "" ) ); const bufferData = `data:application/octet-stream;base64,${base64}`; const blobData = await fetch(bufferData).then((res) => res.blob()); // create a file from the BLOB const file = new File([blobData], "WebViewer_Demo.pdf", { type: "application/pdf", }); // open the file viewer.file.emitOpened({ file: file }); ``` **From memory:** ```typescript // load the document content from an arbitrary source const res = await fetch("http://localhost:3300/pdf/WebViewer_Demo.pdf"); const arrayBuffer = await res.arrayBuffer(); // convert the content to an in memory array const uint8array = new Uint8Array(arrayBuffer); // open the in memory array viewer.file.emitOpened({ data: uint8array }); ``` ### Implement your use case - Find instructions how to implement specific use cases in the [guides](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/) section. - Find more technical information about the PDF Viewer SDK in the [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/). :::info[PDF Web SDK] The PDF Viewer SDK lets you customize some functionalities. If you have specific requirements, you can implement your own PDF viewer using the PDF Web SDK. Implementing the PDF Web SDK allows for greater customization but requires significant development effort than the full PDF Viewer SDK. For more details, review the following sections and pages: - [PDF Web SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-sdk) - [Advanced functionality](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/) --- ## Custom implementation guides **info: These guides focus on the advanced functionality of the [PDF Web SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/#pdf-web-sdk), an underlying layer of the PDF Viewer SDK. If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/).** Refer to the API references for more information about the differences between PDF Viewer SDK and PDF Web SDK. [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/). Learn about various advanced functionalities of the PDF Web SDK. Find a guide for your use case by clicking one of the following cards: --- ## Manage annotations in PDF Add, modify, and delete annotations in a PDF document with the PDF Web SDK. **Steps to work with annotations in a PDF document:** 1. [Initialize the SDK](#initialize-the-sdk) 1. [Create controller](#create-controller) 1. [Open PDF](#open-pdf) 1. [Use AnnotationManager](#use-annotationmanager) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) and learn how to [make static assets available](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#static-assets). ## Initialize the SDK Before instantiating objects and working with PDF Web SDK API, it needs to be initialized. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); } initialize(); ``` ## Create controller A `Pdf.Controller` needs to be created to open the desired document. This controller is responsible for reading document information. ```typescript const controller = new Pdf.Controller(); ``` ## Open PDF Finally the document can be loaded to be later used to access the document information. ```typescript const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); ``` ## Use AnnotationManager ### Overview The [`AnnotationManager`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) is a central interaction hub designed to handle annotation-related operations within a document. It serves as a bridge between user interactions and the underlying document structure, facilitating dynamic changes to annotations based on user actions. It can be access through the `annotations` property in the `Pdf.Document`. ### Get annotations `Annotation` objects can be retrieved via `AnnotationManager.getAll()` or `AnnotationManager.getAllOnPage(page: number)`. The following code snippet shows how to iterate through the annotations on a specific page: ```typescript const annotations = await pdfDocument.annotations.getAllOnPage(1); console.log(annotationsAfter); annotations.forEach((annotation) => { // Do something with the annotation }); ``` ### Add annotations `Annotation` objects can be added individually via `AnnotationManager.add(a: Annotation)` or using the overload `AnnotationManager.add(arr: Annotation[])`. The following code snippet shows how to add annotations to a document: ```typescript // Add a single annotation await pdfDocument.annotations.add( new Pdf.Annotations.FreeTextAnnotation({ page: pdfDocument.pages.getByNumber(1), boundingBox: new Pdf.Geometry.Rectangle(100, 100, 100, 100), content: 'First free text annotation', author: 'John Doe', subject: 'First subject', }) ); // Add multiple annotations await pdfDocument.annotations.add([ new Pdf.Annotations.FreeTextAnnotation({ page: pdfDocument.pages.getByNumber(2), boundingBox: new Pdf.Geometry.Rectangle(200, 200, 200, 200), content: 'Second free text annotation', author: 'John Doe', subject: 'Second subject', }), new Pdf.Annotations.FreeTextAnnotation({ page: pdfDocument.pages.getByNumber(3), boundingBox: new Pdf.Geometry.Rectangle(300, 300, 300, 300), content: 'Third free text annotation', author: 'John Doe', subject: 'Third subject', }), ]); ``` **note: When new `Annotation` objects are created, they are **not** automatically added to the document structure, but instead they are only existing as loosely connected objects.** To effectively add the annotations to the document and to be able to save the document with the new annotations `AnnotationManager.add` or respectively `AnnotationManager.update` must be called. This decoupling of annotation creation and adding is done for flexibility and performance reasons. By deferring annotation updates until explicitly requested, unnecessary rendering operations and updates of the document structure can be avoided. ### Modify annotations Updating `Annotation` objects involves modifying their properties and then calling `AnnotationManager.update(a: Annotation)` or respectively `AnnotationManager.update(arr: Annotation[])` method. The following code snippet shows how to edit a single annotation in a document. ```typescript // Get annotations const annotationsBefore = await pdfDocument.annotations.getAll(); console.log(annotationsBefore); // Edit an annotation annotationsBefore[0].content = annotationsBefore[0].content + ' (Edited)'; annotationsBefore[0].boundingBox.topLeft.x += 100; // Apply changes await pdfDocument.annotations.update(annotationsBefore[0]); // Get annotations again const annotationsAfterEdit = await pdfDocument.annotations.getAll(); console.log(annotationsAfterEdit); ``` **note: When `Annotation` objects are modified, changes are **not** automatically applied to the document, but instead changes are only cached in the `Annotation` object.** To make the changes effective and to be able to save the document with the modifications `AnnotationManager.update` must be called. This decoupling of annotation modification and updating is done for flexibility and performance reasons. By deferring annotation updates until explicitly requested, unnecessary rendering operations and updates of the document structure can be avoided. ### Delete Annotations `Annotation` objects can be deleted individually via `AnnotationManager.delete(a: Annotation)` or using the overload `AnnotationManager.delete(arr: Annotation[])`. The following code snippet shows how to delete an annotations from a document. ```typescript // Get annotations const annotationsBefore = await pdfDocument.annotations.getAll(); console.log(annotationsBefore); // Delete a single annotation await pdfDocument.annotations.delete(annotations[0]); // Delete multiple annotation await pdfDocument.annotations.delete([annotations[1], annotations[2]]); const annotationsAfterDelete = await pdfDocument.annotations.getAll(); console.log(annotationsAfterDelete); ``` ## Full example This full sample demonstrates how to continuously add, update, and delete annotations in a document. ```typescript import { pdfToolsWebSdk, Pdf } from '@pdftools/pdf-web-sdk'; pdfToolsWebSdk.initialize().then(async () => { const controller = new Pdf.Controller(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); let annotationCounter = 0; setInterval(async () => { // move all annotations a bit to the right const annotationsBefore = await pdfDocument.annotations.getAll(); annotationsBefore.forEach((a) => { a.boundingBox.topLeft.x += 10; }); await pdfDocument.annotations.update(annotationsBefore); const annotationsUpdated = await pdfDocument.annotations.getAll(); // if last annotation reaches end of the page -> delete it const lastAnnotation = annotationsUpdated[annotationsUpdated.length - 1]; if (lastAnnotation.boundingBox.topLeft.x > 500) { await pdfDocument.annotations.delete(lastAnnotation); } // if first annotation has moved enough to the right -> insert a new one on the left const firstAnnotation = annotationsUpdated[0]; if (firstAnnotation.boundingBox.topLeft.x > 100) { annotationCounter++; await pdfDocument.annotations.add(new Pdf.Annotations.FreeTextAnnotation({ page: pdfDocument.pages.getByNumber(1), boundingBox: new Pdf.Geometry.Rectangle(10, 100, 50, 50), content: `Annotation #${annotationCounter}`, author: 'John Doe', subject: `Subject #${annotationCounter}`, })); } }, 100); }); ``` --- ## Create custom plugins Learn how to create custom plugins to extend the PDF Viewer SDK with interactive functionality. The PDF Viewer SDK provides a Plugin API that lets you create custom interactive layers and behaviors in the document view. Plugins can add annotations, handle user interactions, render custom overlays, and integrate seamlessly with the viewer. **Steps to create a custom plugin:** 1. [Initialize the Viewer](#initialize-the-viewer) 2. [Understand the Plugin interface](#understand-the-plugin-interface) 3. [Create a custom plugin class](#create-a-custom-plugin-class) 4. [Register the plugin](#register-the-plugin) 5. [Add UI controls to trigger the plugin](#add-ui-controls-to-trigger-the-plugin) 6. [Activate and deactivate the plugin](#activate-and-deactivate-the-plugin) 7. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) and initialize the viewer. ## Initialize the Viewer Before creating plugins, initialize the PDF Viewer SDK and create a viewer instance. ```typescript import { PdfToolsViewer } from '@pdftools/pdf-web-viewer'; const container = document.getElementById('pdftools-viewer-container'); const viewer = new PdfToolsViewer(); await viewer.initialize( { licenseKey: 'your-license-key', }, container ); ``` ## Understand the Plugin interface Plugins implement the [UI.Plugin](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) interface from the PDF Web SDK. This interface defines the contract that all plugins must follow. ```typescript interface Plugin { // Unique identifier for the plugin readonly id: string; // The document view associated with the plugin documentView: DocumentView; // Called when the plugin is activated activate(): void; // Called when the plugin is deactivated or deregistered deactivate(): void; } ``` **Key concepts:** - **Plugin ID**: Each plugin must have a unique identifier used for registration and activation - **DocumentView**: Provides access to the document, pages, and rendering context - **Active state**: Only one plugin can be active at a time - **Lifecycle**: Plugins activate when needed and deactivate when done or when another plugin activates ## Create a custom plugin class Let's create a "Click-to-Place Image" plugin that allows users to select an image file and place it on the PDF document by clicking. ### Create a custom layer First, create a custom layer class that extends [UI.Layer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer). This layer handles rendering on each page. ```typescript import { Layer } from '@pdftools/pdf-web-sdk/es6/UI'; const LAYER_ID = 'click-to-place-image-layer'; class ClickToPlaceImageLayer extends Layer { protected initializeNativeElement(): void { this._nativeElement = document.createElement('canvas'); this._nativeElement.style.position = 'absolute'; this._nativeElement.style.touchAction = 'none'; this._nativeElement.classList.add(LAYER_ID); } protected onSizeChange(): void { this._nativeElement.width = this._size.width; this._nativeElement.height = this._size.height; } protected render(): void {} } ``` ### Create the plugin class Now create the plugin class that implements [UI.Plugin](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin): ```typescript import { Pdf, UI } from '@pdftools/pdf-web-sdk'; import { StampAnnotation } from '@pdftools/pdf-web-sdk/es6/Pdf/Annotations'; import { Size } from '@pdftools/pdf-web-sdk/es6/Pdf/Geometry'; import { DocumentViewPoint, PdfPoint, Point, } from '@pdftools/pdf-web-sdk/es6/Pdf/Geometry/Point'; export class ClickToPlaceImagePlugin implements UI.Plugin { id: string = 'click-to-place-image-plugin'; private _active: boolean = false; private _documentView: UI.DocumentView = null; private _registeredImage: Pdf.PdfImage = null; private _aspectRatio: number = 1; public get active(): boolean { return this._active; } public get documentView(): UI.DocumentView { return this._documentView; } public set documentView(documentView: UI.DocumentView) { this._documentView = documentView; // Listen for new pages added to the viewport and create layers for them this._documentView.addEventListener( 'pageAddedToViewport', (pageNumber) => { if (!this._active) return; const documentViewPage = this._documentView.slidingWindow.get(pageNumber); const layer = new ClickToPlaceImageLayer( LAYER_ID, documentViewPage ); documentViewPage.interactiveLayers = [ ...documentViewPage.interactiveLayers, layer, ]; } ); } /** * Activates the plugin, enabling image placement on click. * @returns {void} */ activate(): void { this._active = true; // Add event listeners this.addEventListeners(); this._documentView.slidingWindow.forEach((documentViewPage) => { const layer = new ClickToPlaceImageLayer( LAYER_ID, documentViewPage ); documentViewPage.interactiveLayers = [ ...documentViewPage.interactiveLayers, layer, ]; }); this._documentView.scrollContainer.style.cursor = 'crosshair'; } /** * Deactivates the plugin, disabling image placement. * @returns {void} */ deactivate(): void { if (!this._active) return; this._active = false; // Remove event listeners this.removeEventListeners(); this._documentView.slidingWindow.forEach((documentViewPage) => { documentViewPage.interactiveLayers = documentViewPage.interactiveLayers.filter( (l) => l.id !== LAYER_ID ); }); // Reset cursor and clear registered image and aspect ratio this._documentView.scrollContainer.style.cursor = 'auto'; this._registeredImage = null; this._aspectRatio = 1; } /** * Sets the image to be placed by the plugin. * @param {File} file - The image file to be placed. * @returns {Promise} */ public async setImage(file: File): Promise { const image = new Image(); const imageUrl = URL.createObjectURL(file); await new Promise((resolve, reject) => { image.onload = () => resolve(); image.onerror = () => reject(new Error('Failed to load image file')); image.src = imageUrl; }); this._aspectRatio = image.width / image.height; URL.revokeObjectURL(imageUrl); const arrayBuffer = await file.arrayBuffer(); const uint8Array = new Uint8Array(arrayBuffer); // Register image in the PDF document this._registeredImage = await this._documentView.pdfDocument.registerImage(uint8Array); } /** * Adds event listeners for the plugin. * @returns {void} */ private addEventListeners(): void { if (!this._documentView) return; this._documentView.addEventListener( 'pagePointerDown', this.handlePageClick ); } /** * Removes event listeners for the plugin. * @returns {void} */ private removeEventListeners(): void { if (!this._documentView) return; this._documentView.removeEventListener( 'pagePointerDown', this.handlePageClick ); } /** * Handles page click events to place the image annotation. * @param {number} pageNumber - The page number where the click occurred. * @param {PointerEvent} event - The pointer event. * @returns {void} */ private handlePageClick = (pageNumber: number, event: PointerEvent) => { if (!this._registeredImage) return; const page = this._documentView.pdfDocument.pages.getByNumber(pageNumber); try { // Calculate the bounding box for the image annotation const pdfRect = this.calculateImageBoundingBox( event, page, pageNumber ); // Create the image annotation const annotation = this.createImageAnnotation(pdfRect, page); // Add the annotation to the document this._documentView.pdfDocument.annotations.add(annotation); } catch (error) { console.error('Error creating image annotation:', error); return; } }; /** * Creates an image annotation on the specified page. * @param {Pdf.Geometry.Rectangle} boundingBox - The bounding box for the annotation. * @param {Pdf.Page} page - The page to add the annotation to. * @returns {StampAnnotation} */ private createImageAnnotation( boundingBox: Pdf.Geometry.Rectangle, page: Pdf.Page ): StampAnnotation { if (!this._registeredImage) { throw new Error('No image registered for annotation creation.'); } if (!page) { throw new Error('Page is required to create image annotation.'); } if (!boundingBox) { throw new Error( 'Bounding box is required to create image annotation.' ); } return new Pdf.Annotations.StampAnnotation({ page, author: 'User', boundingBox, data: { subtype: Pdf.Annotations.StampAnnotationSubtype.Image, image: this._registeredImage, }, }); } /** * Calculates the bounding box for the image annotation based on the click event. * @param {PointerEvent} event - The pointer event. * @param {Pdf.Page} page - The page where the click occurred. * @param {number} pageNumber - The page number where the click occurred. * @returns {Pdf.Geometry.Rectangle} */ private calculateImageBoundingBox( event: PointerEvent, page: Pdf.Page, pageNumber: number ): Pdf.Geometry.Rectangle { if (!this._documentView) { throw new Error('Document view is not set.'); } const documentViewPage = this._documentView.slidingWindow.get(pageNumber); if (!page || !documentViewPage) { throw new Error('Invalid page or document view page.'); } const canvas = documentViewPage.interactiveLayers.find( (l) => l.id === LAYER_ID )?.nativeElement as HTMLCanvasElement; if (!canvas) { throw new Error('Canvas layer not found for image placement.'); } const rect = canvas.getBoundingClientRect(); const clickX = event.clientX - rect.left; const clickY = event.clientY - rect.top; const clickPoint = new Point(clickX, clickY) as DocumentViewPoint; const width = DEFAULT_IMAGE_WIDTH; const height = width / this._aspectRatio; const topLeft = new Point( clickPoint.x - width / 2, clickPoint.y - height / 2 ) as DocumentViewPoint; const documentViewRect = new Pdf.Geometry.Rectangle( topLeft, new Size(width, height) ); return page.transformDocumentViewPointRectangleToPdfPointRectangle( documentViewRect, documentViewPage.size.width, documentViewPage.size.height, Pdf.Rotation.None ); } } ``` **Key implementation details:** - **Custom layer**: Creates canvas layers on each page for handling interactions. - **Image registration**: Uses `document.registerImage()` to register the image with the PDF. - **Coordinate conversion**: Uses `page.transformDocumentViewPointRectangleToPdfPointRectangle()` for accurate placement. - **Guard in deactivate**: Prevents cleanup from running when the plugin wasn't actually active (this is important because the plugin manager calls `deactivate()` on all plugins before activation). ## Register the plugin Register the plugin with the viewer **after** a document is opened. **note: When a document opens, the Viewer internally initializes all registered plugins with the latest `documentView` instance.** ```typescript const PLUGIN_ID = 'click-to-place-image-plugin'; viewer.addEventListener("PdfTools.document.opened", () => { // Initialize and register the ClickToPlaceImagePlugin const imagePlugin = initAndRegisterImagePlugin(viewer, PLUGIN_ID); }); /** * Registers the ClickToPlaceImagePlugin with the given viewer if not already registered. * @param {PdfToolsViewer} viewer - The PDF viewer instance to register the plugin with. * @param {string} pluginId - The unique ID for the plugin. * @returns {ClickToPlaceImagePlugin} The registered ClickToPlaceImagePlugin instance. */ function initAndRegisterImagePlugin( viewer: PdfToolsViewer, pluginId: string ): ClickToPlaceImagePlugin { // Check if plugin is already registered if (!viewer.plugins.get(pluginId)) { // Create a new instance of the plugin const imagePlugin = new ClickToPlaceImagePlugin(); // Register the plugin with the viewer viewer.plugins.register(imagePlugin); return imagePlugin; } return null; } ``` **warning: Plugins need to be registered **after** a document is opened, because they are initialized using the current document view at that time. Note that registering a plugin makes it available for activation, but doesn't activate it automatically.** ## Add UI controls to trigger the plugin Create a button and file input to trigger the plugin. The button can be added to the viewer's toolbar or elsewhere in your UI. ```typescript // Create a custom file input button and append it to the toolbar const button = createFileInputButton(); appendButtonToToolbar(button); const fileInput = button.querySelector( 'input[type="file"]' ) as HTMLInputElement; /** * Creates a button element with a hidden file input for image selection. * @returns {HTMLButtonElement} The created button element. */ function createFileInputButton(): HTMLButtonElement { // Create hidden file input and insert button in toolbar const fileInput = document.createElement('input'); fileInput.type = 'file'; fileInput.accept = 'image/*'; fileInput.hidden = true; const buttonEl = document.createElement('button'); buttonEl.innerHTML = ` `; buttonEl.style.cssText = 'all: unset; width: 40px; height: 40px; cursor: pointer; display: flex; align-items: center; justify-content: center;'; buttonEl.appendChild(fileInput); return buttonEl; } /** * Appends the given button to the viewer's annotation toolbar. * @param {HTMLButtonElement} button - The button element to append. * @returns {void} */ function appendButtonToToolbar(button: HTMLButtonElement): void { const pdfToolsViewerEl = document.querySelector("pdftools-viewer"); const pdfToolsAnnotationToolbarEl = pdfToolsViewerEl.shadowRoot.querySelector( "pdftools-annotation-toolbar" ); pdfToolsAnnotationToolbarEl.shadowRoot .querySelector(".pdftools-annotation-toolbar") .appendChild(button); } ``` ## Add event listeners to support button click and file selection ```typescript // Add event listeners button.addEventListener('click', () => { fileInput.click(); // Trigger hidden file input click to upload image }); fileInput.addEventListener('change', async (e) => { const target = e.target as HTMLInputElement; const file = target.files?.[0]; if (!file) { return; } // Activate the plugin and set the selected image // @NOTE: In this example, we activate the plugin when an image has been selected. // Additionally, pass the selected image to a plugin so that it can register it for use inside the PDF. activatePlugin(viewer, PLUGIN_ID); const imagePlugin = viewer.plugins.get(PLUGIN_ID); await imagePlugin.setImage(file); // Reset input so same file can be selected again target.value = ''; }); /** * Activates the plugin with the given ID in the viewer if not already active. * @param {PdfToolsViewer} viewer - The PDF viewer instance. * @param {string} pluginId - The unique ID of the plugin to activate. * @returns {void} */ function activatePlugin(viewer: PdfToolsViewer, pluginId: string): void { if (!viewer.plugins.isActive(pluginId)) { viewer.plugins.activate(pluginId); } } ``` ## Activate and deactivate the plugin Plugins can be activated and deactivated programmatically using the Plugins API. ### Plugin activation example ```typescript const PLUGIN_ID = 'click-to-place-image-plugin'; // Activate plugin by ID viewer.plugins.activate(PLUGIN_ID); // Check if plugin is active const isActive = viewer.plugins.isActive(PLUGIN_ID); // Get currently active plugin ID const activePluginId = viewer.plugins.getActive(); // Deactivate plugin viewer.plugins.deactivate(PLUGIN_ID); ``` **tip: When a plugin is activated, any previously active plugin is automatically deactivated. Only one plugin can be active at a time.** ### Plugin deactivation example Add keyboard support to deactivate the plugin: ```typescript // On 'Escape' key press, deactivate the plugin if active document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { deactivatePlugin(viewer, PLUGIN_ID); } }); /** * Deactivates the plugin with the given ID in the viewer if it is currently active. * @param {PdfToolsViewer} viewer - The PDF viewer instance. * @param {string} pluginId - The unique ID of the plugin to deactivate. * @returns {void} */ function deactivatePlugin(viewer: PdfToolsViewer, pluginId: string): void { if (viewer.plugins.isActive(pluginId)) { viewer.plugins.deactivate(pluginId); } } ``` ### Listen to plugin events The Plugins API emits events for plugin lifecycle changes: ```typescript // Listen for plugin activation viewer.plugins.addEventListener('activated', (pluginId) => { console.log('Plugin activated:', pluginId); }); // Listen for plugin deactivation viewer.plugins.addEventListener('deactivated', (pluginId) => { console.log('Plugin deactivated:', pluginId); }); // Listen for plugin registration viewer.plugins.addEventListener('registered', (pluginId) => { console.log('Plugin registered:', pluginId); }); // Listen for plugin deregistration viewer.plugins.addEventListener('deregistered', (pluginId) => { console.log('Plugin deregistered:', pluginId); }); ``` ## Full example This complete example demonstrates how to create, register, and use a custom click-to-place image plugin. The example consists of three files that work together: - **[ClickToPlaceImagePlugin.ts](#clicktoplaceimageplugints)**: The plugin class implementation with all the core functionality. - **[index.ts](#indexts)**: The application code that imports the plugin, registers it with the viewer, and sets up UI controls. - **[index.html](#indexhtml)**: The HTML page that loads the application. All three files are necessary to implement this plugin. The plugin class is defined in a separate file for better organization, then imported and used in the main application code. ### ClickToPlaceImagePlugin.ts ```typescript import { Pdf, UI } from '@pdftools/pdf-web-sdk'; import { StampAnnotation } from '@pdftools/pdf-web-sdk/es6/Pdf/Annotations'; import { Size } from '@pdftools/pdf-web-sdk/es6/Pdf/Geometry'; import { DocumentViewPoint, PdfPoint, Point, } from '@pdftools/pdf-web-sdk/es6/Pdf/Geometry/Point'; import { Layer } from '@pdftools/pdf-web-sdk/es6/UI'; // Constants const LAYER_ID = 'click-to-place-image-layer'; const DEFAULT_IMAGE_WIDTH = 100; /** * Layer for handling image placement interactions. */ class ClickToPlaceImageLayer extends Layer { protected initializeNativeElement(): void { this._nativeElement = document.createElement('canvas'); this._nativeElement.style.position = 'absolute'; this._nativeElement.style.touchAction = 'none'; this._nativeElement.classList.add(LAYER_ID); } protected onSizeChange(): void { this._nativeElement.width = this._size.width; this._nativeElement.height = this._size.height; } protected render(): void {} } /** * A plugin that lets users click to place an image annotation on the document. */ export class ClickToPlaceImagePlugin implements UI.Plugin { id: string = 'click-to-place-image-plugin'; private _active: boolean = false; private _documentView: UI.DocumentView = null; private _registeredImage: Pdf.PdfImage = null; private _aspectRatio: number = 1; public get active(): boolean { return this._active; } public get documentView(): UI.DocumentView { return this._documentView; } public set documentView(documentView: UI.DocumentView) { this._documentView = documentView; // Listen for new pages added to the viewport and create layers for them this._documentView.addEventListener( 'pageAddedToViewport', (pageNumber) => { if (!this._active) return; const documentViewPage = this._documentView.slidingWindow.get(pageNumber); const layer = new ClickToPlaceImageLayer( LAYER_ID, documentViewPage ); documentViewPage.interactiveLayers = [ ...documentViewPage.interactiveLayers, layer, ]; } ); } /** * Activates the plugin, enabling image placement on click. * @returns {void} */ activate(): void { this._active = true; // Add event listeners this.addEventListeners(); this._documentView.slidingWindow.forEach((documentViewPage) => { const layer = new ClickToPlaceImageLayer( LAYER_ID, documentViewPage ); documentViewPage.interactiveLayers = [ ...documentViewPage.interactiveLayers, layer, ]; }); this._documentView.scrollContainer.style.cursor = 'crosshair'; } /** * Deactivates the plugin, disabling image placement. * @returns {void} */ deactivate(): void { if (!this._active) return; this._active = false; // Remove event listeners this.removeEventListeners(); this._documentView.slidingWindow.forEach((documentViewPage) => { documentViewPage.interactiveLayers = documentViewPage.interactiveLayers.filter( (l) => l.id !== LAYER_ID ); }); // Reset cursor and clear registered image and aspect ratio this._documentView.scrollContainer.style.cursor = 'auto'; this._registeredImage = null; this._aspectRatio = 1; } /** * Sets the image to be placed by the plugin. * @param {File} file - The image file to be placed. * @returns {Promise} */ public async setImage(file: File): Promise { const image = new Image(); const imageUrl = URL.createObjectURL(file); await new Promise((resolve, reject) => { image.onload = () => resolve(); image.onerror = () => reject(new Error('Failed to load image file')); image.src = imageUrl; }); this._aspectRatio = image.width / image.height; URL.revokeObjectURL(imageUrl); const arrayBuffer = await file.arrayBuffer(); const uint8Array = new Uint8Array(arrayBuffer); // Register image in the PDF document this._registeredImage = await this._documentView.pdfDocument.registerImage(uint8Array); } /** * Adds event listeners for the plugin. * @returns {void} */ private addEventListeners(): void { if (!this._documentView) return; this._documentView.addEventListener( 'pagePointerDown', this.handlePageClick ); } /** * Removes event listeners for the plugin. * @returns {void} */ private removeEventListeners(): void { if (!this._documentView) return; this._documentView.removeEventListener( 'pagePointerDown', this.handlePageClick ); } /** * Handles page click events to place the image annotation. * @param {number} pageNumber - The page number where the click occurred. * @param {PointerEvent} event - The pointer event. * @returns {void} */ private handlePageClick = (pageNumber: number, event: PointerEvent) => { if (!this._registeredImage) return; const page = this._documentView.pdfDocument.pages.getByNumber(pageNumber); try { // Calculate the bounding box for the image annotation const pdfRect = this.calculateImageBoundingBox( event, page, pageNumber ); // Create the image annotation const annotation = this.createImageAnnotation(pdfRect, page); // Add the annotation to the document this._documentView.pdfDocument.annotations.add(annotation); } catch (error) { console.error('Error creating image annotation:', error); return; } }; /** * Creates an image annotation on the specified page. * @param {Pdf.Geometry.Rectangle} boundingBox - The bounding box for the annotation. * @param {Pdf.Page} page - The page to add the annotation to. * @returns {StampAnnotation} */ private createImageAnnotation( boundingBox: Pdf.Geometry.Rectangle, page: Pdf.Page ): StampAnnotation { if (!this._registeredImage) { throw new Error('No image registered for annotation creation.'); } if (!page) { throw new Error('Page is required to create image annotation.'); } if (!boundingBox) { throw new Error( 'Bounding box is required to create image annotation.' ); } return new Pdf.Annotations.StampAnnotation({ page, author: 'User', boundingBox, data: { subtype: Pdf.Annotations.StampAnnotationSubtype.Image, image: this._registeredImage, }, }); } /** * Calculates the bounding box for the image annotation based on the click event. * @param {PointerEvent} event - The pointer event. * @param {Pdf.Page} page - The page where the click occurred. * @param {number} pageNumber - The page number where the click occurred. * @returns {Pdf.Geometry.Rectangle} */ private calculateImageBoundingBox( event: PointerEvent, page: Pdf.Page, pageNumber: number ): Pdf.Geometry.Rectangle { if (!this._documentView) { throw new Error('Document view is not set.'); } const documentViewPage = this._documentView.slidingWindow.get(pageNumber); if (!page || !documentViewPage) { throw new Error('Invalid page or document view page.'); } const canvas = documentViewPage.interactiveLayers.find( (l) => l.id === LAYER_ID )?.nativeElement as HTMLCanvasElement; if (!canvas) { throw new Error('Canvas layer not found for image placement.'); } const rect = canvas.getBoundingClientRect(); const clickX = event.clientX - rect.left; const clickY = event.clientY - rect.top; const clickPoint = new Point(clickX, clickY) as DocumentViewPoint; const width = DEFAULT_IMAGE_WIDTH; const height = width / this._aspectRatio; const topLeft = new Point( clickPoint.x - width / 2, clickPoint.y - height / 2 ) as DocumentViewPoint; const documentViewRect = new Pdf.Geometry.Rectangle( topLeft, new Size(width, height) ); return page.transformDocumentViewPointRectangleToPdfPointRectangle( documentViewRect, documentViewPage.size.width, documentViewPage.size.height, Pdf.Rotation.None ); } } ``` ### index.ts ```typescript import { PdfToolsViewer } from '@pdftools/pdf-web-viewer'; import { ClickToPlaceImagePlugin } from './ClickToPlaceImagePlugin'; async function init() { const container = document.getElementById('pdftools-viewer-container'); const viewer = new PdfToolsViewer(); await viewer.initialize( { licenseKey: 'your-license-key', }, container ); const PLUGIN_ID = 'click-to-place-image-plugin'; viewer.addEventListener("PdfTools.document.opened", () => { // Initialize and register the ClickToPlaceImagePlugin const imagePlugin = initAndRegisterImagePlugin(viewer, PLUGIN_ID); }); // Create a custom file input button and append it to the toolbar const button = createFileInputButton(); appendButtonToToolbar(button); const fileInput = button.querySelector('input[type="file"]') as HTMLInputElement; // Add event listeners button.addEventListener('click', () => { fileInput.click(); // Trigger hidden file input click to upload image }); fileInput.addEventListener('change', async (e) => { const target = e.target as HTMLInputElement; const file = target.files?.[0]; if (!file) return; // Activate the plugin and set the selected image activatePlugin(viewer, PLUGIN_ID); const imagePlugin = viewer.plugins.get(PLUGIN_ID); await imagePlugin.setImage(file); // Reset input so same file can be selected again target.value = ''; }); // On 'Escape' key press, deactivate the plugin if active document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { deactivatePlugin(viewer, PLUGIN_ID); } }); // Listen to plugin activation events viewer.plugins.addEventListener('activated', (pluginId) => { // Update button color when plugin is activated if (pluginId === PLUGIN_ID) { button.querySelector('svg').style.fill = '#0D8FF2'; } }); // Listen to plugin deactivation events viewer.plugins.addEventListener('deactivated', (pluginId) => { // Update button color when plugin is deactivated if (pluginId === PLUGIN_ID) { button.querySelector('svg').style.fill = '#10D183'; } }); } /** * Activates the plugin with the given ID in the viewer if not already active. */ function activatePlugin(viewer: PdfToolsViewer, pluginId: string): void { if (!viewer.plugins.isActive(pluginId)) { viewer.plugins.activate(pluginId); } } /** * Deactivates the plugin with the given ID in the viewer if it is currently active. */ function deactivatePlugin(viewer: PdfToolsViewer, pluginId: string): void { if (viewer.plugins.isActive(pluginId)) { viewer.plugins.deactivate(pluginId); } } /** * Registers the ClickToPlaceImagePlugin with the given viewer if not already registered. */ function initAndRegisterImagePlugin( viewer: PdfToolsViewer, pluginId: string ): ClickToPlaceImagePlugin { if (!viewer.plugins.get(pluginId)) { const imagePlugin = new ClickToPlaceImagePlugin(); viewer.plugins.register(imagePlugin); return imagePlugin; } return null; } /** * Creates a button element with a hidden file input for image selection. */ function createFileInputButton(): HTMLButtonElement { const fileInput = document.createElement('input'); fileInput.type = 'file'; fileInput.accept = 'image/*'; fileInput.hidden = true; const buttonEl = document.createElement('button'); buttonEl.innerHTML = ` `; buttonEl.style.cssText = 'all: unset; width: 40px; height: 40px; cursor: pointer; display: flex; align-items: center; justify-content: center;'; buttonEl.appendChild(fileInput); return buttonEl; } /** * Appends the given button to the viewer's annotation toolbar. */ function appendButtonToToolbar(button: HTMLButtonElement): void { const pdfToolsViewerEl = document.querySelector("pdftools-viewer"); const pdfToolsAnnotationToolbarEl = pdfToolsViewerEl.shadowRoot.querySelector( "pdftools-annotation-toolbar" ); pdfToolsAnnotationToolbarEl.shadowRoot .querySelector(".pdftools-annotation-toolbar") .appendChild(button); } init(); ``` ### index.html ```html Custom Plugin Example ``` ## Plugin lifecycle Understanding the plugin lifecycle helps ensure proper resource management: 1. **Registration**: Plugin is registered with `viewer.plugins.register(plugin)` and becomes available for use. 2. **Activation**: Plugin is activated with `viewer.plugins.activate(pluginId)`, calling the `activate()` method. 3. **Active state**: Plugin handles user interactions and renders content while active 4. **Deactivation**: Plugin is deactivated when another plugin activates or via `viewer.plugins.deactivate(pluginId)`. 5. **Cleanup**: Resources are released in the `deactivate()` method. :::warning[Important] The plugin manager calls `deactivate()` on **all registered plugins** before activating a new one. If needed, guard your `deactivate()` method with `if (!this._active) return;` to prevent unintentional cleanup of resources. ## Best practices Follow these best practices when creating custom plugins: 1. **Unique IDs**: Use descriptive, unique plugin IDs to avoid conflicts. 2. **Resource cleanup**: Always remove event listeners and layers in `deactivate()`. 3. **Guard deactivate**: Add `if (!this._active) return;` at the start of `deactivate()` to prevent premature cleanup. 4. **Lazy registration**: Register plugins after a document is opened to ensure `pdfDocument` is available. 5. **Error handling**: Wrap SDK operations in try-catch blocks for robust error handling. 6. **State management**: Track plugin state carefully to avoid inconsistent behavior. 7. **Coordinate systems**: Remember to convert between canvas and PDF coordinate spaces using `transformDocumentViewPointRectangleToPdfPointRectangle()`. 8. **Single responsibility**: Keep plugins focused on a single, well-defined task. ## Further reading - [UI.Plugin Interface](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) - Plugin interface specification. - [UI.Layer Class](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer) - Layer rendering documentation. - [Manage events](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/event-emitter) - Event handling patterns. - [Manage annotations](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/annotations) - Working with PDF annotations. --- ## Read PDF information Learn how to read information from a PDF document using the PDF Web SDK. The PDF Web SDK lets you access document information without instantiating a viewer and without the need of a server to process the document. Use this functionality to display document information such as the author or page count to the user before rendering the document (for example, in a file chooser). **Steps to read information from a PDF document:** 1. [Initialize the SDK](#initialize-the-sdk) 1. [Create controller](#create-controller) 1. [Open PDF](#open-pdf) 1. [Read document information programmatically](#read-document-information-programmatically) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) and learn how to [make static assets available](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#static-assets). ## Initialize the SDK Before instantiating objects and working with PDF Web SDK API, it needs to be initialized. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); } initialize(); ``` ## Create controller A `Pdf.Controller` needs to be created to open the desired document. This controller is responsible for reading document information. ```typescript const controller = new Pdf.Controller(); ``` ## Open PDF Finally the document can be loaded to be later used to access the document information. ```typescript const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); ``` ## Read document information programmatically The document loaded via the `Pdf.Controller` has several properties that can be used to access document information. Some of them are directly accessible, others are stored in the `metadata`. ```typescript // properties stored in the metadata const metadata = await pdfDocument.getMetadata(); console.log(`title = ${metadata.title}`); console.log(`author = ${metadata.author}`); console.log(`creation date = ${metadata.creationDate}`); // direct properties console.log(`page count = ${pdfDocument.pageCount}`); ``` **warning: The Metadata API is still under development and not all information available in the PDF might already be available on the API.** **tip: For a full list of information refer to the api-references for [Pdf.Document](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) and [Pdf.Metadata](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Metadata).** ## Full example This full sample demonstrates how to open a document and log document information to the console. ```typescript import { pdfToolsWebSdk, Pdf } from '@pdftools/pdf-web-sdk'; pdfToolsWebSdk.initialize().then(async () => { const controller = new Pdf.Controller(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); // properties stored in the metadata const metadata = await pdfDocument.getMetadata(); console.log(`title = ${metadata.title}`); console.log(`author = ${metadata.author}`); console.log(`creation date = ${metadata.creationDate}`); // direct properties console.log(`page count = ${pdfDocument.pageCount}`); }); ``` --- ## Navigate within PDF Learn how to navigate within a PDF file with the PDF Web SDK. The PDF Viewer SDK can programmatically navigate within a document. Let users navigate to a specific page of interest in a PDF document by implementing this functionality. **This guide explains how to:** 1. [Go to a page](#go-to-a-page) 1. [Go to a destination](#go-to-a-destination) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/). Navigating within a PDF document requires a `DocumentView`. Learn how to [view a document](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/document-view). ## Go to a page The `DocumentView` offers convenient ways to navigate to a page, either incrementally using `nextPage()` or `previousPage()`, or by page number using `goToPage(pageNumber: number)`. The following code snippet shows basic navigation: ```typescript // go to a specific page documentView.goToPage(5); // go to next page documentView.nextPage(); // go to previous page documentView.previousPage(); ``` ## Go to a destination **note: This functionality is not yet available but will be available in future releases.** ## Full example This full sample demonstrates how to navigate to the page of the first annotation after opening a document. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; pdfToolsWebSdk.initialize().then(async () => { // create document view const container = document.querySelector('#pdftools-viewer-container'); const documentView = new UI.DocumentView(container); // create controller and open document const controller = new Pdf.Controller(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); await documentView.initialize(pdfDocument); // get the first annotation in the document const annotationList = await pdfDocument.annotations.getAll(); if(annotationList.length > 0) { const firstAnnotation = annotationList[0]; documentView.goToPage(firstAnnotation.page.pageNumber); } }); ``` --- ## Search text in PDF The PDF Viewer SDK lets you programmatically search for text within documents. Let users see their searched terms highlighted. **Steps to view a PDF file:** 1. [Initialize the SDK](#initialize-the-sdk) 1. [Create controller](#create-controller) 1. [Open PDF](#open-pdf) 1. [Define the SearchStrategy](#define-the-searchstrategy) 1. [Execute search with the SearchService](#execute-search-with-the-searchservice) 1. [Listen to search events](#listen-to-search-events) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) and learn how to [make static assets available](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#static-assets). ## Initialize the SDK Before instantiating objects and working with PDF Web SDK API, it needs to be initialized. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); } initialize(); ``` ## Create controller A `Pdf.Controller` needs to be created to open the desired document. This controller is responsible for processing document events such as rendering pages. ```typescript const controller = new Pdf.Controller(); ``` ## Open PDF Now the document can be loaded. ```typescript const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); ``` **note: For a pure programmatic approach the document loaded does not necessarily need to be passed to a `UI.DocumentView`.** ## Define the SearchStrategy To search within a document a `SearchStrategy` is required. It creates the connection between the document to be searched, the search parameters, and the `SearchService`. ```typescript // create the search strategy const searchStrategy: Pdf.Search.DocumentTextSearchStrategy = new Pdf.Search.DocumentTextSearchStrategy(pdfDocument); ``` **tip: For searching text the `DocumentTextSearchStrategy` is provided ready-to-use, but other custom search strategies can be derived from `SearchStrategy` if needed.** ## Execute search with the SearchService ```typescript // create the search service const searchService = new Pdf.Search.DocumentTextSearchService(searchStrategy); // execute the search const searchExecution = searchService.execute({ query: 'pdf', caseSensitive: false, regularExpression: false, }); // wait for search results const searchResults = await searchExecution.result; ``` **tip: The supported search params passed to `DocumentTextSearchService.execute` are defined by the `SearchStrategy` used.** In this sample `DocumentTextSearchStrategy` is used, which supports passing a `query` string, `caseSensitive` flag, and `regularExpression` flag. ## Listen to search events Instead of waiting until the search was completely finished, listening to search events is a good practice to allow in-time user feedback. The following snippet outlines the supported events and how to listen them. ```typescript // convenience function used in the following event listeners const resultToString = (result: DocumentTextSearchResult) => { return `'${result.text}' found on page ${result.pageNumber} in '${result.contextText}' `; }; // listen to searchStarted events searchExecution.addEventListener('searchStarted', (result) => { console.log("search started: " + resultToString(result)); }); // listen to searchResultsFound events searchExecution.addEventListener('searchResultsFound', (result) => { console.log("search results found: " + resultToString(result)); }); // listen to searchFinished events searchExecution.addEventListener('searchFinished', (result) => { console.log("search finished: " + resultToString(result)); }); // listen to searchCanceled events searchExecution.addEventListener('searchCanceled', () => { console.log("search canceled"); }); // listen to errorOccurred events searchExecution.addEventListener('errorOccurred', (error) => { console.log("search error occurred: " + error); }); ``` **tip: For more details on events learn how to [Manage events](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/event-emitter).** ## Full example This full sample demonstrates how to configure and execute a search, and log search results to the console. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); const controller = new Pdf.Controller(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); // create the search strategy const searchStrategy: Pdf.Search.DocumentTextSearchStrategy = new Pdf.Search.DocumentTextSearchStrategy(pdfDocument); // create the search service const searchService = new Pdf.Search.DocumentTextSearchService(searchStrategy); // execute the search const searchExecution = searchService.execute({ query: 'pdf', caseSensitive: false, regularExpression: false, }); // wait for search results const searchResults = await searchExecution.result; // convenience function used in the following event listeners const resultToString = (result: DocumentTextSearchResult) => { return `'${result.text}' found on page ${result.pageNumber} in '${result.contextText}' `; }; // listen to searchStarted events searchExecution.addEventListener('searchStarted', (result) => { console.log("search started: " + resultToString(result)); }); // listen to searchResultsFound events searchExecution.addEventListener('searchResultsFound', (result) => { console.log("search results found: " + resultToString(result)); }); // listen to searchFinished events searchExecution.addEventListener('searchFinished', (result) => { console.log("search finished: " + resultToString(result)); }); // listen to searchCanceled events searchExecution.addEventListener('searchCanceled', () => { console.log("search canceled"); }); // listen to errorOccurred events searchExecution.addEventListener('errorOccurred', (error) => { console.log("search error occurred: " + error); }); } initialize(); ``` --- ## View a PDF Learn how to create a document view with the PDF Web SDK. **Steps to view a PDF file:** 1. [Initialize the SDK](#initialize-the-sdk) 1. [Define the view element](#define-the-view-element) 1. [Attach the view to page](#attach-the-view-to-the-page) 1. [Create controller](#create-controller) 1. [Open PDF](#open-pdf) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) and learn how to [make static assets available](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#static-assets). ## Initialize the SDK Before instantiating objects and working with PDF Web SDK API, it needs to be initialized. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); } initialize(); ``` ## Define the view element To view a document you have to create a page containing a container element as the root element for the viewer. ```html ``` ## Attach the view to the page This root element then can be used to create a `UI.DocumentView`. ```typescript const container = document.querySelector('#pdftools-viewer-container'); const documentView = new UI.DocumentView(container); ``` ## Create controller A `Pdf.Controller` needs to be created to open the desired document. This controller is responsible for processing document events such as rendering pages. ```typescript const controller = await new Pdf.Controller().initialize(); ``` ## Open PDF Finally the document can be loaded and passed to the initialization of the `UI.DocumentView` for viewing it. ```typescript const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); documentView.initialize(pdfDocument); ``` ## Full example This full sample demonstrates how to create a document view using the PDF Web SDK. ** index.html ** ```html PDF Viewer SDK ``` ** index.ts ** ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); const container = document.querySelector('#pdftools-viewer-container'); const documentView = new UI.DocumentView(container); const controller = await new Pdf.Controller().initialize(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); documentView.initialize(pdfDocument); } initialize(); ``` --- ## Manage events Listen to and programmatically dispatch built-in and custom events with the PDF Web SDK. The PDF Viewer SDK `EventEmitter` class provides a powerful and type-safe mechanism for managing and dispatching events by classes which are designed to emit events. By default, there are multiple classes which support events, such as `Pdf.Document`, `Pdf.Page`, `UI.DocumentView`. You can also create custom classes extending `EventEmitter`. The `EventEmitter` template type describes which events are supported by a concrete class and specifies the expected structure of the provided callback functions. **This guide explains the following:** 1. [Generic EventEmitter concept](#generic-eventemitter-concept) 1. [Listening to built-in events](#listening-to-built-in-events) 1. [Full example](#full-example) --- :::info[Before you begin] If you prefer to test a demo or would like to explore the basic functionalities of this SDK, review [Getting started with the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/). **note: The `EventEmitter` class is a general-purpose utility for type-safe event handling. You can extend it to create your own custom event emitters independently of the PDF Viewer SDK. However, many PDF Viewer SDK classes (such as `Document`, `Page`, and `DocumentView`) also extend `EventEmitter`, letting you listen to their built-in events.** To work with events from PDF Viewer SDK classes, first learn the basics of the PDF Web SDK, such as how to [view a document](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/document-view) or [read document information](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/document-information). ## Generic EventEmitter concept The `EventEmitter` class makes use of event maps - a type safe approach to define the name and the parameters of supported events. For example, if you want to define an event named `'sampleEventOccurred'` that takes one parameter of type `number`, you can describe this with an interface like this: ```typescript interface SampleEventMap { sampleEventOccurred: (sampleParam: number) => void; } ``` When now creating an `EventEmitter` using this event map, the `EventEmitter` template type will make the typescript compiler assure, that only suitable event names and handlers are accepted on `addEventListener`, `dispatchEvent`, and `removeEventListener`. ```typescript import { Core } from '@pdftools/pdf-web-sdk'; // extend EventEmitter using the event map defined above class SampleEventEmitter extends Core.EventEmitter {} // Create an instance of class which extends EventEmitter const eventEmitter = new SampleEventEmitter(); ``` Now event function is typesafe, for example: ```typescript const goodListener = (sampleParam: number) => { console.log('Sample event occurred', sampleParam); }; const badListener = (sampleParam: string) => { console.log('Sample event occurred', sampleParam); }; // add event listener // OK eventEmitter.addEventListener('sampleEventOccurred', goodListener); // NOT OK: unsupported event name eventEmitter.addEventListener('sampleEvent', goodListener); // NOT OK: wrong listener parameters eventEmitter.addEventListener('sampleEventOccurred', badListener); // dispatch event // OK eventEmitter.dispatchEvent('sampleEventOccurred', [123]); // NOT OK: unsupported event name eventEmitter.dispatchEvent('sampleEvent', [123]); // NOT OK: wrong listener parameters eventEmitter.dispatchEvent('sampleEventOccurred', ["foo"]); // remove event listener // OK eventEmitter.removeEventListener('sampleEventOccurred', goodListener); // NOT OK: unsupported event name eventEmitter.removeEventListener('sampleEvent', goodListener); // NOT OK: wrong listener parameters eventEmitter.removeEventListener('sampleEventOccurred', badListener); ``` ## Listening to built-in events Listening to built-in events works exactly as described in the generic concept above. For each class emitting events you find the definition of the supported events as an event map in the API references, for example: - [Controller](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) ➡️ [ControllerEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/ControllerEventMap) - [Document](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) ➡️ [DocumentEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentEventMap) - [DocumentView](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) ➡️ [DocumentViewEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) - [Page](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) ➡️ [PageEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PageEventMap) ## Full example This full example demonstrates how to react to changes in the `DocumentView` and log them to the console. ```typescript import { pdfToolsWebSdk, Pdf, UI } from '@pdftools/pdf-web-sdk'; async function initialize() { await pdfToolsWebSdk.initialize({ path: './pdftools-web-sdk/', }); const container = document.querySelector('#pdftools-viewer-container'); const documentView = new UI.DocumentView(container); const controller = new Pdf.Controller(); const pdfDocument = await controller.openDocument({ uri: '/pdf/WebViewer_Demo.pdf', }); const zoomListener = (zoomLevel: number) => { const percent = zoomLevel * 100; console.log(`zoom changed to ${percent}%`); }; documentView.addEventListener('zoomChanged', zoomListener); documentView.initialize(pdfDocument); } initialize(); ``` --- ## Release notes(Pdf-web-viewer) Learn about the changes, additions, and fixes in the PDF Viewer SDK. ## Version 5 ### Version 5.15.1 29 April 2026 #### Added - The `Annotation` class supports storing custom data through the `privateData` property of type `string`. The property persists across save and load cycles, letting applications attach domain-specific metadata to each annotation. - The Document API emits a `pageRendered` event when a page finishes rendering. The event payload is the rendered page number. #### Changed - The `addAnnotation()`, `deleteAnnotation()`, and `updateAnnotation()` methods on `viewer.document` accept either a single annotation or an array of annotations, supporting batch operations with a single call. - The `viewer.document.getPage()` method returns a `Page` synchronously instead of a `Promise`. Update existing code to call `viewer.document.getPage(pageNumber)` directly, without `await`. #### Fixed - Before this update, setting `ViewerConfig.devicePixelRatio` caused the viewer to crash at browser zoom levels other than 100% because the calculated canvas dimensions didn't match the rendered buffer. As a consequence, viewer instances that configured `devicePixelRatio` failed whenever users zoomed the browser. With this update, the viewer derives the effective device pixel ratio from the rendered buffer size. As a result, the viewer renders correctly at any browser zoom level. - Before this update, text selection under certain circumstances ended one character before the end of the selected word. As a consequence, viewer users couldn't include the final character when selecting a complete word. With this update, the text-selection logic includes the last glyph in the range. As a result, viewer users can select complete words. ### Version 5.15.0 16 April 2026 #### Added - Viewer users can create ink annotations (freehand drawings) on PDF documents, customize the stroke color, opacity, and line width, erase parts of the drawing, and edit annotations by moving, resizing, locking, or deleting them. - Developers can set the annotation author using the `user` option in `ViewerConfig` during initialization, or the `setUser()` method on `PdfToolsViewer` at runtime. The `getUser()` method returns the configured user. The viewer applies this value when creating or editing annotations. - The `document.addAnnotation()` method lets developers add annotations to PDF documents programmatically. - Developers can configure the device pixel ratio (DPR) using the `devicePixelRatio` option in `ViewerConfig` to balance rendering sharpness and performance. Higher values increase sharpness, while lower values improve performance. - Viewer users can navigate sidebar panels with the keyboard, move the focus between elements using the `Tab` key, navigate menu items with the arrow keys, and activate buttons with the `Enter` or `Spacebar` keys. #### Changed - The `viewer.initialize()` method throws an error when called on an already initialized viewer instance. Developers must dispose of the existing instance before reinitializing. Use `viewer.addEventListener("PdfTools.viewer.initialized")` to detect when initialization completes. - Updated embedded fonts for improved license compliance. #### Fixed - Before this update, the lock/unlock button in the sticky note modal didn't reflect the current annotation state. With this update, the button stays synchronized with the contextual menu. - Before this update, viewer users couldn't create redaction annotations on touchscreen devices. This has been resolved. - Image upload validates file types and prevents viewer users from selecting unsupported formats. - The thumbnail panel displays equal left and right margins. - Redaction annotations are included when saving documents as FDF. ### Version 5.14.0 3 March 2026 #### Added - Viewer users can create rectangle and ellipse shape annotations. Users can customize the border color, fill color, and border width, and edit these annotations by moving, resizing, locking, or deleting them. - Toolbar buttons display dark-themed tooltips on hover. - PDF Viewer SDK supports FDF (Forms Data Format). Save or download documents as FDF by setting the `saveAsFdf` option to `true`: ```ts viewer.document.save({saveAsFdf: true}); ``` - A loading spinner and progress bar provide visual feedback while the viewer uploads and opens documents. - Viewer users can set the input document parameter when initializing the viewer to skip the document upload screen: ```ts viewer.initialize({inputDocument: {uri: 'url_to_a_file'}, ...}); viewer.initialize({inputDocument: {data: file}, ...}); ``` #### Changed - Redesigned the thumbnails panel. The active page displays with a blue highlight. - Toolbar dropdown components (zoom, fit mode, page layout, and pagination) close automatically when users click outside or open another dropdown. - The pagination component supports page number input, letting users navigate to a specific page directly. - Updated icons throughout the viewer, including the file open icon and line ending icons in the annotation popover. - Redesigned the document upload screen. - Rewrote the document opening flow, removing code duplication and memory leaks. #### Fixed - Toolbar icons no longer shift position when navigating to pages with two or more digits. - Dropdown panels (zoom, fit mode, layout, and annotation popovers) no longer overlap. Opening one panel closes any other open panel. - Opening the search or thumbnails panel no longer deactivates the active plugin. - The sticky notes popover closes immediately when activating stamp or redaction plugins, rather than waiting for the sidebar to open. - Before this update, the app layout used a deprecated layout system. As a result, page margins were inconsistent on mobile and tablet devices. With this update, the app layout uses a consistent margin system across desktop, mobile, and tablet devices. ### Version 5.13.0 23 January 2026 #### Added - Viewer users can create redaction annotations by selecting text, drawing rectangles on the document, or redacting the current page or a specified range of pages. A dedicated **Redact** panel displays all redaction annotations, allowing users to lock them to prevent accidental edits or delete them. - Viewer users can download a redacted version of the document using **Apply Redactions** button in the **Redact** panel. Annotations are not included in the downloaded file. #### Changed - Zoom level change events are debounced, which enhances performance when users rapidly zoom in and out of documents. - Refactored the PDF Viewer SDK API. As a result, the API has reduced the number of parameters and configuration options, delivering the same functionality with greater simplicity and usability. - Improved and faster build process, valid source maps, and reliable ECMAScript Modules (ESM) and Universal Module Definition (UMD) bundles. #### Fixed - Replaced delete and lock icons across all context menus with consistently sized icons, making actions easier to identify. ### Version 5.12.1 18 December 2025 #### Added - Users can add text annotations (free-text notes) to PDFs, supporting rich text formatting with options for font family, font size, text color, alignment, and styles such as bold, italic, and underline. Text annotations can be edited inline, moved by dragging, or deleted. - Users can now add image annotations to PDFs by selecting and placing an image on the document. Existing image annotations can be moved, resized, deleted, or locked. - With this release, the PDF Web Viewer enables developers to create custom plugins using a dedicated plugin API. Developers can register, activate, and deactivate plugins, create layers for drawing on the document view, and add buttons to control plugin state. - The PDF Web SDK exposes accessibility events and keyboard interactions through the `TextSelectionPlugin`. The `cursorPositionChanged` event enables tracking of cursor position changes. The `keyDown` event exposes keyboard interactions. In text selection mode, users can click on text to display a cursor. They can move the text using the arrow keys. Users can select text with `Shift` + `Arrow`, navigate word by word with `Ctrl` or `Cmd` + `Arrow`, and select word by word with `Shift` + `Ctrl` or `Cmd` + `Arrow`. - Added support for redaction annotations as a `TextMarkupType` in the PDF Web SDK. As a result, developers can implement redaction annotation creation in their applications. #### Changed - The `textSelectionChanged` event now provides additional geometry data. This includes selection quadrilaterals with page numbers, start and end page numbers, and the selected text content. The following method was changed: The following methods changed:
`textSelectionChanged()`
From: `textSelectionChanged: (selectedText: string) => void`
To: `textSelectionChanged: (textSelectionData: TextSelection) => void`
- The PDF Web Viewer enhanced web components for improved accessibility, introducing updated button, menu, dropdown, and toolbar components. All components are now fully keyboard accessible and screen reader compatible. The following methods changed:
`hideComponents()`
From: `hideComponents: (components: HideableComponentConfigName[]) => void`
To: `hideComponents: (paths: string[] | string[][]) => void`
`showComponents()`
From: `showComponents: (components: HideableComponentConfigName[]) => void`
To: `showComponents: (paths: string[] | string[][]) => void`
`overrideButtonBehavior()`
From: `overrideButtonBehavior: (buttonName: string, eventName: string, callback: () => void ) => void`
To: `overrideButtonBehavior: (path: string | string[], eventName: OverridableButtonEventType, callback: () => void) => void;`
### Version 5.11.1 16 December 2025 #### Fixed - Fixed license handling to ensure full offline operation. ### Version 5.11.0 17 November 2025 #### Added - Users can choose whether to include annotations when printing a PDF. The print dialog contains an **Include annotations** toggle, which is deselected by default. When enabled, the printed PDF includes annotations; when disabled, annotations are not included in the resulting PDF output. - With this update, users can select and then modify the following annotation types as specified: - Stamp annotations: Delete, resize, move, and lock. - Line and arrow annotations: Delete, resize, move, lock, change color, width, and endings. - Cloud annotations: Delete, resize, move, lock, change outline color, fill color, and outline width. - Highlight annotations: Delete and change color. - Custom layers support an optional `dispose` method for lifecycle management. The PDF Web SDK automatically calls this method when the viewer removes pages from the viewport, allowing proper cleanup of resources and event listeners. #### Fixed - Line annotation arrows render with the correct fill color, matching the line stroke color. - The `PdfTools.documentView.pageChanged` event triggers correctly when scrolling or changing pages. - The `PdfTools.toolbar.zoom.updated` event triggers for all zoom level changes. As a result, zoom levels function correctly when users adjust them using a touchpad or mouse wheel. ### Version 5.10.0 23 October 2025 #### Added - The PDF Viewer SDK introduces a print dialog with configurable dots per inch (DPI) settings. The viewer now prints PDFs with vector graphics and text preservation, ensuring high-quality printouts, rather than rasterized, low-resolution bitmaps. - The toolbar and sidebar are now responsive, automatically adapting to smaller screen sizes. On mobile devices, the left toolbar moves to the top under the fixed header, while the viewer hides the sidebar by default to maximize viewing space. Users can access the sidebar through toggle controls when needed. - Line and arrow annotations now support opacity customization. Users can adjust the opacity level when drawing or creating these annotations for better visual control and document clarity. #### Fixed - Touch gesture interactions on mobile devices now work correctly. Users can scroll the canvas using swipe gestures and zoom in or out using pinch gestures across iOS and Android devices. - Line annotation previews now correctly respect the current zoom level. The preview during creation matches the final annotation size and position at all zoom levels, eliminating visual inconsistencies. - Fixed a memory leak that occurred when loading and navigating large PDFs. The viewer no longer accumulates excess memory, preventing browser crashes and performance degradation during extended use. - Cloud annotations (annotations with stylized, scalloped borders) are visible in the annotations panel. They display with the same design and behavior as other annotation types, including the cloud icon, metadata, and clickable navigation. ### Version 5.9.0 3 October 2025 #### Added - The PDF Viewer SDK now supports line annotations, enabling users to draw straight lines on PDF documents. Users and developers can customize them with colors, thickness, and line patterns for use cases such as directional markings or visual separation. - Users can now create arrow annotations to point directions to specific elements in PDF documents. These are a type of line annotation with an arrowhead at the start and/or end, useful for reviews, comments, or instructional documents. - Cloud annotations have been introduced, allowing users to highlight areas with a stylized, scalloped border. Users and developers can customize the border color, fill color, and line width. - A new annotation-changed event system triggers when users add, modify, or delete annotations. The system includes a reference to the annotation object for inspection and manipulation, with safeguards against recursive triggering. - The PDF Viewer SDK now includes a dispose method that cleans all viewer resources, including controllers, document views, annotations, and event listeners. As a result, memory leaks are prevented and repeated creation and disposal of viewers without performance issues is enabled. #### Changed - Refactored the PDF Viewer SDK API to provide a more powerful, scalable, and easier-to-use interface, simplifying extension and customization. #### Fixed - You can now load viewer instances simultaneously. Each instance is isolated from others, preventing interference and conflicts. - Previously, reopening a document with an active plugin (for example, text markup or notes) caused deactivation issues. This release resolves these issues, allowing you to activate and deactivate plugins reliably. As a result, plugin activation and deactivation now work correctly across document sessions. ### Version 5.8.0 16 September 2025 #### Added - With this release, the PDF Viewer SDK presents a new annotation viewing panel. - Viewer users can now navigate documents using a clickable list of headings (also known as the document outline, or bookmarks). #### Fixed - As of this release, the PDF Viewer SDK delivers improved support for large files. This was achieved by raising memory limits and resolving a related processing issue. ### Version 5.7.0 03 July 2025 #### Changed - You can now work with multiple interactive layers simultaneously, instead of being limited to just one. This enhancement enables the creation of more dynamic and layered PDF experiences. #### Fixed - The worker thread is now properly cleaned up when the `WorkerController` is disposed, preventing unnecessary background activity. - Page re-rendering now functions correctly after annotations are moved across pages, ensuring that changes appear as expected. - The `pdfToolsWebSdk.version` property previously returned the value `dev`. As of this update, the `pdfToolsWebSdk.version` property returns the correct version string. ### Version 5.6.0 09 June 2025 #### Added - Viewer users can now add text stamp annotations by choosing from the predefined set of stamps, including texts such as **Approved**, **Confidential**, **Draft**, and many others. - A loading spinner is displayed while the PDF Viewer SDK is opening a file to provide a progress indicator. - As of this update, viewer users can create text markup annotation gestures on mobile devices. #### Fixed - Previously, users could not scroll upward when using the fit-to-page mode. This issue has been resolved. - The background visual for the zoom slider was missing. With this update, the correct background is now restored. - The `pdfToolsWebSdk.version` property previously returned value `undefined`. As of this update, the `pdfToolsWebSdk.version` property returns the correct version string. ### Version 5.5.0 29 April 2025 #### Added - The PDF Viewer SDK lets you implement text markup annotations, enabling users to highlight, underline, strike through, and create squiggly line annotations in documents. - With this update, the PDF Viewer SDK includes an accessibility layer, improving usability for users who rely on assistive technologies. For more information, review [Enable accessibility layer](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer#enable-accessibility-layer) section. - You can add custom headers using HTTP requests when opening a document, improving integration flexibility. For more information, review [Provide custom HTTP headers when opening a document](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer#provide-custom-http-headers-when-opening-a-document) section. - As of this update, the viewer users can hide the annotation bar. #### Fixed - Previously, under certain circumstances, a part of a sticky note bar remained displayed upon closing a sticky note. This update resolves the described issue. - To improve consistency and maintainability of the component's styling, the CSS variables referenced in the styles are now defined adequately with default values. ### Version 5.4.0 26 March 2025 #### Added - You can now drag sticky note annotations between pages. - You can now customize the color theme of the PDF Viewer SDK using the following set of 6 CSS variables: - `--background-color` - `--color-text-primary` - `--color-text-secondary` - `--hover-background-color` - `--secondary-color` - `--active-color` #### Changed - In the PDF Viewer SDK API: - Functions responsible for emitting events have been renamed from `eventname()` to `emitEventname()`. As a result, it is clear that the purpose of these functions is to emit events. - The parameter name for callback functions has been changed from `fn` to `callback`. - New PDF Web SDK API methods simplify conversion between PDF and document viewpoints, making custom layer implementation easier. For more details, review [Page](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) class API reference. #### Fixed - An issue where the cursor was stuck in the loading state has been resolved. - Previously, the thumbnails would not have been updated if the document had been changed. With this release, the issue has been resolved. ### Version 5.3.0 27 February 2025 #### Added - You can now interact with link annotations that navigate you to external resources or specific locations within the PDF. - Developers can now implement custom text markup annotations through the PDF Web SDK. This feature lets you create, edit, and delete highlights, underlines, squiggly lines, and strikethroughs, as well as customize their color. For more information, review [Class: TextMarkupAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/TextMarkupAnnotation) in the PDF Web SDK API references. ### Version 5.2.0 7 February 2025 #### Added - You can now add, create, edit, and delete sticky note annotations. A new annotation contextual menu lets you add text, edit the color of annotations, and lock the annotation to prevent accidental edits. #### Changed - With this update, the new layering mechanism separates search and text selection. As a result, the performance of the PDF Viewer SDK is now improved. ### Version 5.1.1 21 January 2025 #### Added - You can now override the save button behavior to initiate custom actions. For more information, review [Modify save button behavior](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer#modify-save-button-behavior) section. #### Changed - Previously, when you opened a corrupt PDF, the PDF Viewer SDK auto-repair feature tried to fix the corrupted file. As a consequence, fixing the file could invalidate some digital signatures. With this update, you can disable the auto-repair with a boolean to prevent unwanted modifications of the original documents. For more information, review [Disable auto-repair feature](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer#disable-auto-repair-feature) section. ### Version 5.1.0 18 November 2024 #### Added - The PDF Viewer SDK can now navigate you to the selected search result. #### Fixed - PDF Viewer SDK Licensing is now pointing to the correct endpoint. - Before this update, there was a race condition when initializing the PDF Viewer SDK with the Angular framework. With this update, the issue was fixed. - Under certain circumstances, the PDF Viewer SDK could capture events outside of the canvas. As of this update, the underlying issue has been fixed, and the canvas size is the only space where you can capture events. - The API references and their generation process have been updated. ### Version 5.0.0 11 September 2024 #### Added - The PDF Viewer SDK architecture was rewritten entirely. As a result, the SDK now consists of two packages: - PDF Web Viewer: An SDK that lets you implement PDF viewer capabilities with search. - PDF Web SDK: The functionality the PDF Web Viewer requires and additional features that let you completely customize the SDK. It's recommended that you try the PDF Web Viewer first. The PDF Web Viewer lets you customize some functionalities. You can implement your own PDF viewer using the PDF Web SDK if you have specific requirements. Implementing the PDF Web SDK lets you create a customized viewer from scratch but requires more development effort than the full PDF Viewer SDK. - The PDF Web Viewer is now working on both desktop and mobile. - Only the free Viewer-only version is available. ## Previous versions :::warning[Version incompatibility] While the PDF Viewer SDK version 5 introduces new and improved functionality, it is also incompatible with implementations of the PDF Viewer SDK version 4. Hence this page provides release notes for version 5.0.0 and above. For previous release notes, refer to the [version 4 release notes](https://www.pdf-tools.com/docs/pdf-web-viewer/4/release-notes). --- ## Standard implementation overview Learn about the standard functionality of the PDF Viewer SDK and customization capabilities. Find a guide for your use case by clicking one of the following cards: --- ## Customize the PDF Viewer SDK(Standard-implementation) Learn about the customizable elements of the PDF Viewer SDK to modify various functionalities. ## Modify save button behavior Download the original documents with their digital signature unaffected by any changes by using the following sample code. Customize the **Save** button to save the original document without applying any changes made during viewing or editing. The default button behavior is overridden using `overrideButtonBehavior` API method. To enable this functionality, edit your `index.ts` using the following code: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { const viewer = new PdfToolsViewer(); const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({}, container); // Overrides the "Save" button to download the original document without changes made in the viewer. viewer.overrideButtonBehavior( [ "pdftools-toolbar", "#pdftools-save-document-btn", ], "click", async () => { await viewer.document.save({ saveOriginal: true }); } ); } initialize(); ``` ## Disable auto-repair feature Disable automatic repair operations on PDF files by setting the `autoRepairDisabled` property to `true` when opening a document using the following sample code. Using this configuration when maintaining the original integrity of the document is critical. This ensures that the PDF Viewer SDK does not perform any repairs that can alter the file's structure or invalidate digital signatures. To enable this functionality, edit your `index.ts` using the following code: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { const viewer = new PdfToolsViewer(); const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({}, container); // URL of the PDF file (as a string) const url: string = "https://example.com/sample.pdf"; viewer.document.open({ uri: url, autoRepairDisabled: true }); } initialize(); ``` ## Enable accessibility layer Enable an accessibility layer for individuals who rely on assistive technologies in the PDF Viewer SDK, such as screen readers. When the accessibility layer is enabled, the SDK generates an invisible HTML structure that mirrors the text content layout of PDFs. This structure allows screen readers to interpret the text. Additionally, when users hover over text fragments with a mouse, the screen reader reads the corresponding content aloud. To enable this functionality, edit your `index.ts` using the following code: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { const viewer = new PdfToolsViewer(); const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({ accessibilityLayerEnabled: true, }, container); } initialize(); ``` ## Provide custom HTTP headers when opening a document When opening a document, include user-defined HTTP headers, such as authentication tokens. Custom HTTP headers can allow secure access to protected resources by passing necessary credentials or metadata in the request. To enable this functionality, edit your `index.ts` using the following code: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { const viewer = new PdfToolsViewer(); const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({}, container); // URL of the PDF file (as a string) const url: string = "https://example.com/sample.pdf"; viewer.document.open({ uri: url, httpOptions: { headers: { Authorization: "Bearer [TOKEN]", }, }, }); } initialize(); ``` --- ## View a PDF(Standard-implementation) Load and view PDF documents using the PDF Viewer SDK. The viewer is embedded into a webpage and dynamically appended. The following sample showcases an example of the `index.ts`: ```typescript import { PdfToolsViewer } from "@pdftools/pdf-web-viewer"; async function initialize() { const viewer = new PdfToolsViewer(); const container = document.getElementById("pdftools-viewer-container"); await viewer.initialize({}, container); } initialize(); ``` --- ## Other shell tools and SDKs This category includes documentation for legacy products whose functionality was partly or entirely replaced by other solutions and SDKs. Before using these products, check whether the latest Pdftools products cover their functionality. The following list includes the latest products: - [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) - [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/) - [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) - [PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/) If you have any questions about the feature coverage of the Pdftools SDK, don't hesitate to contact our sales team through the [Contact page](https://www.pdf-tools.com/contact/). ## Categories The Other shell tools and SDKs are split into three categories grouped by the following sidebar labels: - [4-Heights®](#4-heights) - [3-Heights®](#3-heights) - [Classic](#classic) These three categories represent previous Pdftools product generations. ### 4-Heights® The 4-Heights® generation includes [PDF Toolbox SDK](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-toolbox-sdk): A comprehensive SDK for PDF manipulation. ### 3-Heights® The 3-Heights® generation includes specialized tools for specific PDF operations. Many of these products are maintained for existing customers, with their functionality gradually being integrated into the Pdftools SDK, Toolbox add-on, or Conversion Service. - [Image to PDF Converter](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/image-pdf-converter): Convert images to PDF and PDF/A. - [PDF Analysis & Repair](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-analysis-repair): Analyze and repair PDF documents. - [PDF Extract](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-extract): Extract content from PDF documents. - [PDF Merge Split](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-merge-split): Merge and split PDF documents. - [PDF OCR](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-ocr): Add OCR text layers to PDF documents. - [PDF Optimizer](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-optimizer): Optimize and reduce the size of your PDF files. - [PDF Printer](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-printer): High-performance automated PDF printing. - [PDF Producer](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-producer): Create PDF and PDF/A from Windows applications. - [PDF Security](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-security): Sign, encrypt, and protect PDF documents. - [PDF Validator](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-validator): Validate PDF conformance to standards. - [PDF to Image Converter](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-image-converter): Convert PDF pages to images. - [PDF to PDF/A Converter](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-pdfa-converter): Convert PDF to PDF/A for archiving. - [Scan to PDF Server](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/scan-to-pdf-server): Service-based scan post-processing. ### Classic The classic products are no longer actively developed and are maintained only for existing customers with valid licenses. Review the [Legacy products](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/legacy-products) page for links to documentation of the PDF Command Line Suite, Batch Stamp Tool, PDF Prep Tool Suite, and Form Filling Tool. --- ## Code samples for Image to PDF Converter :::caution[Product update] This product has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/)**. Image to PDF Converter lets you convert image files to PDF documents, including PDF/A with searchable output files. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## Image to PDF Converter documentation The Image to PDF Converter has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/convert/)**, providing improved performance, quality and reliability. On this page, you can learn how to migrate from the Image to PDF Converter to the Pdftools SDK. :::caution[Image to PDF Converter documentation and code examples] The PDF to Image Converter is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/Image2PdfAPI.pdf), [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/Image2PdfShell.pdf), and [Service developer](https://www.pdf-tools.com/public/downloads/manuals/Image2PdfService.pdf) guides. You can also explore the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/image-pdf-converter-code)** for examples of how to use the Image to PDF Converter API. ## Migrate from the Image to PDF Converter to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for converting raster images to PDF and PDF/A documents. :::tip[Pdftools SDK quick start] Get the full sample on GitHub for image to PDF conversion using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Img2PdfDefault), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Img2PdfDefault), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Img2PdfDefault), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/MultipleImg2Pdf). --- ## Legacy products documentation Here you can find all the documentation you need for legacy Classic Pdftools products. ## PDF Command Line Suite The PDF Command Line Suite offers a series of tools to manipulate PDF documents and extract information. The features offered by this product are now available with [Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/). - **[Shell](https://pdf-tools.com/public/downloads/manuals/CmdLineSuiteShell.pdf)** ## Batch Stamp Tool The PDF Batch Stamp Tool lets you create textual or image stamps on PDF documents. [Toolbox add-on](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/) for the Pdftools SDK now provides features of the PDF Batch Stamp Tool. Previously, [PDF Security](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-security) also offered similar functionality and was replaced with the [Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/) and the Toolbox add-on. For more information, review [Add and remove content](https://www.pdf-tools.com/docs/pdf-tools-sdk/toolbox/edit). - **[User guide](https://pdf-tools.com/public/downloads/manuals/BatchStampToolShell.pdf)** ## PDF Prep Tool Suite The PDF Prep Tool Suite is a programming library for creating, splitting, and merging PDF documents. The features offered by this product are now available with [Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/). - **[API](http://pdf-tools.com/public/downloads/manuals/PdfPrepToolSuiteAPI.pdf)** ## Form Filling Tool The Form Filling Tool is a command line tool to create, edit, fill in, and delete form fields. The features offered by this product are now available with [Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/). - **[User guide](https://pdf-tools.com/public/downloads/manuals/FormFillingToolShell.pdf)** --- ## PDF Analysis & Repair documentation [PDF Analysis & Repair](https://www.pdf-tools.com/products/validation-repair/pdf-analysis-repair/) is a high-performance SDK that lets you check corrupt PDFs, restore PDF properties, and extract legible content. It analyzes PDF documents with regard to PDF specifications. Shell Use the command line to validate and fix PDFs. API Send API calls to validate and fix PDFs. :::note[Documentation for other versions] PDF Analysis & Repair is no longer available as a service. For existing customers, access the [Service version developer guide](https://www.pdf-tools.com/public/downloads/manuals/PdfRepairService.pdf). --- ## PDF Extract documentation :::info[Extract with Pdftools SDK] This product has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/)**. You can find this functionality specifically in the **Toolbox add-on**. [PDF Extract](https://www.pdf-tools.com/products/manipulation/pdf-extract/) is a robust SDK that lets you extract content and metadata, including fonts, images, and text. You extract and query various attributes and page content from a PDF document. Shell Use the command line to transform PDF content into useable information. API Send API calls to transform PDF content and metadata into useable information. --- ## PDF to Image Converter documentation View the [API developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2ImageAPI.pdf), [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2ImageShell.pdf), and [Service developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2ImageService.pdf) guides. --- ## PDF Merge Split documentation PDF Merge / Split has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/assemble/)**, providing improved performance and reliability. On this page, you can learn how to migrate from PDF Merge / Split to the Pdftools SDK. :::caution[PDF Merge / Split documentation and code examples] PDF Merge / Split is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/PdfSplitMergeAPI.pdf), and [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/PdfSplitMergeShell.pdf) guides. ## Migrate from PDF Merge / Split to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for merging and splitting PDF documents. :::tip[Pdftools SDK quick start] Get the full sample on GitHub for assembling PDF documents using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Merge), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Merge), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Merge), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Merge). --- ## PDF OCR documentation 3-Heights PDF OCR lets you enhance PDF documents using information detected by an OCR engine. Enterprise Add-on Enterprise features for PDF OCR processing. API Integrate PDF OCR functionality into your applications. Shell Use the command line for PDF OCR processing. --- ## Code samples for PDF Optimizer :::caution[Product update] The PDF Optimizer has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/)**. See the [Migrate from the PDF Optimizer to the Pdftools SDK](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-optimizer) documentation. PDF Optimizer lets you compress and optimize PDFs for the web, printing, and long-term archiving. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## PDF Optimizer documentation The PDF Optimizer has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/optimize/)**, providing improved quality, optimized compression, and reliability improvements. On this page, you can learn how to migrate from the PDF Optimizer to the Pdftools SDK. :::caution[PDF Optimizer documentation and code examples] The PDF Optimizer is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/PdfOptimizeAPI.pdf), [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/PdfOptimizeShell.pdf), and [Service developer](https://www.pdf-tools.com/public/downloads/manuals/PdfOptimizeService.pdf) guides. You can also explore the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-optimizer-code)** for examples of how to use the PDF Optimizer API. ## Migrate from the PDF Optimizer to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for selecting and applying the best possible compression and optimization parameters. :::tip[Pdftools SDK optimization quick start] Get the full sample on GitHub for PDF optimization using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/OptimizerSimple), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/OptimizerSimple), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/OptimizerSimple), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/OptimizerSimple). ### Optimization profiles The PDF Optimizer provides pre-configured optimization profiles suitable for specific use cases. The same profiles are also available in the Pdftools SDK. You can map [optimization profiles](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/N_PdfTools_Optimization_Profiles.htm) from the PDF Optimizer to the Pdftools SDK using the following table: | PDF Optimizer optimization profile | Pdftools SDK optimization profile | |------------------------------------|-----------------------------------| | `eOptimizationProfileWeb` | [Web](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_Profiles_Web.htm) | | `eOptimizationProfileArchive` | [Archive](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_Profiles_Archive.htm) | | `eOptimizationProfilePrint` | [Print](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_Profiles_Print.htm) | | `eOptimizationProfileDefault` or `eOptimizationProfileMax` | [MinimalFileSize](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_Profiles_MinimalFileSize.htm) | | `eOptimizationProfileMRC` | [Mrc](https://api-reference.pdf-tools.com/pdfsdk/1.5/dotnet/html/T_PdfTools_Optimization_Profiles_Mrc.htm) | :::note[Not implemented] 1. The Pdftools SDK does not yet support linearization. ### Image compression settings The Pdftools SDK selects the best image compression settings based on your chosen optimization profile, but you can still adjust the settings to suit your specific needs. #### Compression algorithm selection The PDF Optimizer lets you set image compression types with bitonal, continuous, and indexed color spaces. With the Pdftools SDK, you can use the [optimization profile](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/N_PdfTools_Optimization_Profiles.htm) and [compression algorithm selection](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_CompressionAlgorithmSelection.htm) to determine the image compression type. For images with bitonal and indexed color spaces, you can map the [optimization profile](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/N_PdfTools_Optimization_Profiles.htm) and image color space to the equivalent PDF Optimizer compression types using the following table: | Optimization profile | Image color space | PDF Optimizer compression type | |----------------------|--------------------|-----------------------------------| | Web | Bitonal | `eComprAttemptSource` or `eComprAttemptGroup4` | | Web | Indexed | `eComprAttemptSource` or `eComprAttemptFlate` | | Print | Bitonal | `eComprAttemptSource` or `eComprAttemptGroup4` | | Print | Indexed | `eComprAttemptSource` or `eComprAttemptFlate` | | Archive | Bitonal | `eComprAttemptSource` or `eComprAttemptGroup4` or `eComprAttemptJBIG2` | | Archive | Indexed | `eComprAttemptSource` or `eComprAttemptFlate` | | MinimalFileSize | Bitonal | `eComprAttemptSource` or `eComprAttemptGroup4` or `eComprAttemptJBIG2` | | MinimalFileSize | Indexed | `eComprAttemptSource` or `eComprAttemptFlate` or `eComprAttemptLZW` | For images with continuous color spaces, you can map the Pdftools SDK [optimization profile](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/N_PdfTools_Optimization_Profiles.htm) and [compression algorithm selection](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/T_PdfTools_Optimization_CompressionAlgorithmSelection.htm) to the equivalent PDF Optimizer compression types using the following table: | Optimization profile | Compression algorithm selection | PDF Optimizer compression type | |-----------------------------------|--------------------------------------|-----------------------------------| | Web | PreserveQuality | `eComprAttemptSource` | | Web | Speed | `eComprAttemptJPEG` or `eComprAttemptSource` | | Web | Balanced | `eComprAttemptJPEG` or `eComprAttemptSource` | | Archive | PreserveQuality | `eComprAttemptJPEG2000` or `eComprAttemptFlate` | | Archive | Speed | `eComprAttemptJPEG` or `eComprAttemptSource` | | Archive | Balanced | `eComprAttemptJPEG` or `eComprAttemptJPEG2000` or `eComprAttemptSource` | | Print | PreserveQuality | `eComprAttemptNone` | | Print | Speed | `eComprAttemptJPEG` or `eComprAttemptSource` | | Print | Balanced | `eComprAttemptJPEG` or `eComprAttemptJPEG2000` or `eComprAttemptSource` | | MinimalFileSize | PreserveQuality | `eComprAttemptSource` | | MinimalFileSize | Speed | `eComprAttemptJPEG` or `eComprAttemptSource` | | MinimalFileSize | Balanced | `eComprAttemptJPEG` or `eComprAttemptJPEG2000` or `eComprAttemptSource` | #### Image quality for lossy compression The PDF Optimizer `ImageQuality` property is equivalent to the Pdftools SDK [CompressionQuality](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_ImageRecompressionOptions_CompressionQuality.htm) property. Images with bitonal and indexed color spaces are not affected by the `ImageQuality` property. The Pdftools SDK always uses lossless compression for images with bitonal and indexed color spaces. #### Downsampling The PDF Optimizer allows to independently set the target and threshold DPI for bitonal, monochrome, and color images. The Pdftools SDK lets you set the target DPI for monochrome and color images. Bitonal images are not resampled to avoid adding significant image artifacts during optimization. In the Pdftools SDK, the default threshold for resampling an image always equals 1.4 times the `ResolutionDPI` property. You can override the default value by using the `ThresholdDPI` property. | PDF Optimizer property | Pdftools SDK property | |------------------------|-----------------------| | ColorResolutionDPI | ResolutionDPI | | ColorThresholdDPI | ThresholdDPI | | MonochromeResolutionDPI | ResolutionDPI | | MonochromeThresholdDPI | ThresholdDPI | | BitonalResolutionDPI | -1.0 (do not resample) | | BitonalThresholdDPI | -1.0 (do not resample) | #### Clipping images There is no equivalent to the PDF Optimizer `ClipImages` property. The Pdftools SDK clips images when possible. #### Removing images There is no equivalent to the PDF Optimizer `RemoveImages` property. Use the Toolbox add-on of the Pdftools SDK to [remove and redact content](https://www.pdf-tools.com/docs/toolbox-add-on/guides/redact/) from a PDF file before optimizing. #### Reducing color complexity The PDF Optimizer `ReduceColorComplexity` property is equivalent to the Pdftools SDK [ReduceColorComplexity](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_ImageRecompressionOptions_ReduceColorComplexity.htm) property. #### Dithering bitonal images There is no equivalent to the PDF Optimizer `DitheringMode` property. The Pdftools SDK doesn't downsample or dither bitonal images. ### Merge and remove content The Pdftools SDK selects the best content removal settings based on your chosen optimization profile, but you can still adjust the settings to suit your specific needs. #### Optimize resources There is no equivalent to the PDF Optimizer `OptimizeResources` property. The Pdftools SDK optimizes resources when possible. #### Merge, compress, and remove fonts * There is no equivalent to the PDF Optimizer `SubsetFonts` property. The Pdftools SDK subsets fonts when possible. * There is no equivalent to the PDF Optimizer `CompactFont` property. The Pdftools SDK compacts fonts when possible. * The PDF Optimizer `MergeEmbeddedFonts` property is equivalent to the Pdftools SDK [FontOptions.Merge](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_FontOptions_Merge.htm) property. * The PDF Optimizer `RemoveStandardFonts` property is equivalent to the Pdftools SDK [FontOptions.RemoveStandardFonts](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_FontOptions_RemoveStandardFonts.htm) property. #### Flatten and remove content The PDF Optimizer and the Pdftools SDK have equivalent functionality for flatting and removing content from a PDF file during optimization. The `Strip` property from the PDF Optimizer is replaced by the [RemovalOptions](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/Properties_T_PdfTools_Optimization_RemovalOptions.htm) class of the Pdftools SDK using the following table: | PDF Optimizer strip type | Pdftools SDK RemovalOption | |--------------------------|----------------------------| | eStripAnnots | [Annotations](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_Annotations.htm) | | eStripForms | [FormFields](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_FormFields.htm) | | eStripLinks | [Links](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_Links.htm) | | eStripAlternates | [RemoveAlternateImages](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveAlternateImages.htm) | | eStripMetadata | [RemoveMetadata](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveMetadata.htm) | | eStripOutputIntents | [RemoveOutputIntents](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveOutputIntents.htm) | | eStripPieceInfo | [RemovePieceInfo](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemovePieceInfo.htm) | | eStripSpider | `True` for all profiles except Archive | | eStripStructTree | [RemoveStructureTree](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveStructureTree.htm) | | eStripThumb | [RemoveThumbnails](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveThumbnails.htm) | The PDF Optimizer property `FlattenSignatureFields` is replaced by the Pdftools SDK [RemovalOptions.RemoveSignatureAppearances](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Optimization_RemovalOptions_RemoveSignatureAppearances.htm) property. ### Encryption Refer to the Pdftools SDK documentation to [encrypt and decrypt a PDF file](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/secure/encrypt-a-pdf/) when using the optimization features of the Pdftools SDK. ### Extract image data and font files There is no equivalent to the PDF Optimizer `ListFonts`, `ExtractFonts`, `ListImages`, or `ExtractImages` in the Pdftools SDK. Instead, use the Toolbox add-on of the Pdftools SDK to [extract information](https://www.pdf-tools.com/docs/toolbox-add-on/guides/extract/) from a PDF file before optimizing. ### Set document metadata and information Refer to the Toolbox add-on documentation to [manage metadata](https://www.pdf-tools.com/docs/toolbox-add-on/guides/manage-metadata/) in a PDF file before or after optimizing. ### Work with memory streams In the PDF Optimizer, special functions like `OpenMem`, `SaveInMemory`, and `GetPdf` store and retrieve file data in memory. In the Pdftools SDK all methods such as [OptimizeDocument](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/M_PdfTools_Optimization_Optimizer_OptimizeDocument.htm) that input or output file data use `Stream` objects. The `Stream` object can be either a file stream or a memory stream, so you can easily choose whether to store and retrieve file data in memory or on the file system. ### Migrate from the PDF Optimizer shell tool to the Pdftools SDK Shell Tool Unlike Pdftools' previous products which required a different shell tool for each function, the Pdftools SDK provides a single shell tool that includes all SDK functions, including optimization. The PDF Optimizer `pdfoptimize` shell tool is replaced by the Pdftools SDK Shell Tool. See [Pdftools SDK Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool/) getting started guide for more information. To access general help for the Pdftools SDK Shell Tool, run: ``` pdf help ``` #### Use profiles The Pdftools SDK Shell Tool uses [optimization profiles](#optimization-profiles) to preset many optimization flags. To access help for specific optimization profiles, run one of the following commands: ``` pdf help optimize-web pdf help optimize-archive pdf help optimize-print pdf help optimize-minimal pdf help optimize-mrc ``` #### Pdftools SDK Shell Tool optimization flags You can map flags from the PDF Optimizer to the Pdftools SDK using the following table: PDF Optimizer flag Description Pdftools SDK flag -c Set the color conversion Not supported -cff Compress Type1 fonts (convert to CFF) Always `true` -cms Set the color management engine Always `none` -dmr Resolution for monochrome images See `-dr` -dmt Threshold for monochrome images See `-dt` -dcr Resolution for color images See `-dr` -dct Threshold for color images See `-dt` -dbr Resolution for bitonal images Not supported -dbt Threshold for bitonal images Not supported -dr Resolution in DPI `-dr` -dt Threshold in DPI `-dt` -fb Compression types for bitonal images Preselected based on optimization profile -fc Compression types for color and grayscale images `-as` -ff Force re-compression Not supported -fi Compression types for indexed (paletted) images Preselected based on optimization profile -fn File name Input file is inferred from command syntax -ft Force compression types Not supported -fv Minimum PDF version Not supported -h Dithering mode for bitonal images Not supported -id Set value in the document information dictionary `-t <title>` `-a <author>` `-s <subject>` `-k <keyword1,keyword2>` etc. `-c <creator>` `-cd <creation date>` `-md <modification date>` -lf List fonts Not supported -li List images Not supported -lk Set license key `-lk` -m Merge embedded font programs `-nmf` to disable -ml Compression type for MRC layers `-as` -mlq Image quality for MRC layers `-lq` -mlr Resolution in DPI for MRC layers `-lr` -mm Compression type for the MRC mask Always `eComprAttemptJBIG2` -mp Compression type for MRC cutout pictures Not supported -o Owner password `-opw <perms>` -oc Clip images Always `true` -od Optimize resources Always `true` -ol Linearize only Not supported -or Remove redundant objects Always `true` -ow Optimize for the web Use `optimize-web` command -owa Optimize for the Web automatically Use `optimize-web` command -p Permission flags See `<perms>` parameter of `-opw` -pr Set an optimization profile Profile is inferred from command -pw Read an encrypted PDF file `-pw` -q Compression quality `-q` -rc Reduce image color complexity Always `true` -ri Remove images Always `false` -rf Remove embedded font program Not supported -rs Remove embedded standard fonts `-rsf` -s Subset fonts Always `true` -sa Strip article threads `-kat` (keep article threads) -sf Flatten and strip form fields and annotations `-csa` and `-csf` -sff Flatten and strip form fields `-csf` -sfl Flatten and strip link annotations `-csa` -sfa Flatten and strip other annotations `-csa` -sfs Flatten appearances of signature fields `-csa` -sia Flatten and strip invisible annotations `-csa` -si Strip alternate images `-rai` -sm Strip metadata `-km` (keep metadata) -so Strip output intents `-roi` -sp Strip page piece info (private application data) `-kpi` (keep piece info) -ss Strip document tree structure `-kst` (keep document tree structure) -st Strip thumbnails `-kt` (keep thumbnails) -sw Strip spider (web capture) info Always `true` -u User password `-upw` -v Verbose mode `-verbose` -xf Extract fonts Not supported -xi Extract images Not supported --- ## Code samples for PDF to PDF/A Converter :::caution[Product update] This product has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/)**. PDF to PDF/A Converter converts PDFs to PDF/A format. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## PDF to PDF/A Converter documentation The PDF to PDF/A Converter has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/)**, providing improved performance and reliability. On this page, you can learn how to migrate from the PDF to PDF/A Converter to the Pdftools SDK. :::caution[PDF to PDF/A Converter documentation and code examples] The PDF to PDF/A Converter is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2PdfAPI.pdf), [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2PdfShell.pdf), and [Service developer](https://www.pdf-tools.com/public/downloads/manuals/Pdf2PdfService.pdf) guides. You can also explore the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-pdfa-converter-code)** for examples of how to use the PDF to PDF/A Converter API. ## Migrate from the PDF to PDF/A Converter to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for converting PDF documents to PDF/A. :::tip[Pdftools SDK quick start] Get the full sample on GitHub for PDF to PDF/A conversion using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/ValidateConvert), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/ValidateConvert), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/ValidateConvert), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/ValidateConvert). --- ## Code samples for PDF Printer With PDF Printer, you can send multiple documents in a single job, send multiple jobs, and even customize the print settings used. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## PDF Printer documentation [PDF Printer](https://www.pdf-tools.com/products/viewing-printing/pdf-printer/) is a high-performance SDK for automated (background) printing of PDF documents on all Windows printers including PostScript and PCL, and on virtual printers. Shell Use the command line to automate batch PDF print jobs. API Send API calls to transform PDF content and metadata into useable information. :::tip[See it in action!] Check out the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-printer-code)** for examples on how to use PDF Printer. :::note[Documentation for other versions] PDF Printer is no longer available as a service. For existing customers, access the [Service version developer guide](https://www.pdf-tools.com/public/downloads/manuals/PdfPrinterService.pdf). --- ## PDF Producer documentation 3-Heights PDF Producer lets you create files conforming to PDF and PDF/A from any Windows application via the print function. User guide Learn how to use PDF Producer to create PDF and PDF/A files. --- ## Code samples for PDF Security :::caution[Product update] This product has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/)**. With PDF Security, you can digitally sign multiple PDF documents using online signing services and local certificates. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## PDF Security documentation PDF Security has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/)**, providing improved performance and reliability. On this page, you can learn how to migrate from PDF Security to the Pdftools SDK. :::caution[PDF Security documentation and code examples] PDF Security is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/PdfSecurityAPI.pdf), [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/PdfSecurityShell.pdf), and [Service developer](https://www.pdf-tools.com/public/downloads/manuals/PdfSecurityService.pdf) guides. You can also explore the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-security-code)** for examples of how to use the PDF Security API. ## Migrate from PDF Security to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for digitally signing and securing PDF documents. :::tip[Pdftools SDK quick start] Get the full sample on GitHub for signing a PDF using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/BuiltInSign), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/BuiltInSign), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/BuiltInSign), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/BuiltInSign). --- ## PDF Toolbox SDK The **PDF Toolbox SDK** has been rebranded as the **[Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/)**. The Toolbox add-on is fully compatible with the PDF Toolbox SDK and offers the same functionality with continued support and updates. ## PDF Toolbox SDK → Toolbox add-on - **Product name change**: PDF Toolbox SDK is now called Toolbox add-on. - **Full compatibility**: All APIs and functionality remain the same. - **Documentation**: The Toolbox add-on has comprehensive, updated documentation. - **Legacy docs preserved**: Previous PDF Toolbox SDK documentation (versions 4.2, 4.3, and 4.4) is preserved as legacy versions under the Toolbox add-on documentation. ## Access legacy documentation If you need to access the legacy PDF Toolbox SDK documentation, it's preserved under the Toolbox add-on: - [Legacy 4-H Toolbox version 4.4 documentation](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/) - [Legacy 4-H Toolbox version 4.3 documentation](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.3/) - [Legacy 4-H Toolbox version 4.2 documentation](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.2/) ## Toolbox add-on documentation Visit **[Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/)** documentation. --- ## Code samples for PDF Validator :::caution[Product update] This product has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/)**. PDF Validator lets you check single documents or an entire batch for conformance with the ISO PDF and PDF/A standards. This product has been replaced. Find code examples for the replacement product in the **[Pdftools SDK code examples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/)** and **[Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples/)**. --- ## PDF Validator documentation The PDF Validator has been replaced by the **[Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/validate/)**, providing improved performance and reliability. On this page, you can learn how to migrate from the PDF Validator to the Pdftools SDK. :::caution[PDF Validator documentation and code examples] The PDF Validator is no longer available to new customers. However, you can still view the [API developer](https://www.pdf-tools.com/public/downloads/manuals/PdfValidatorAPI.pdf), and [Shell tool developer](https://www.pdf-tools.com/public/downloads/manuals/PdfValidatorShell.pdf) guides. You can also explore the **[code samples](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-validator-code)** for examples of how to use the PDF Validator API. ## Migrate from the PDF Validator to the Pdftools SDK Migrate to the Pdftools SDK to use a streamlined interface for validating PDF and PDF/A documents. :::tip[Pdftools SDK quick start] Get the full sample on GitHub for PDF/A validation using the Pdftools SDK in [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/ValidateSimple), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/ValidateSimple), [C](https://github.com/pdf-tools/sdk-examples-c/tree/main/ValidateSimple), and [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/ValidateSimple). --- ## Scan to PDF Server documentation 3-Heights Scan to PDF Server is a service-based application for scan post processing. User guide Learn how to use Scan to PDF Server for scan post processing. --- ## AI Smart Redact AI Smart Redact detects and permanently removes sensitive information from PDFs. The service runs entirely within your infrastructure, so no data leaves your environment. AI Smart Redact is built for regulated industries with strict data-sovereignty and compliance requirements: government, financial services, insurance, healthcare, and legal sectors, that require full data sovereignty, provable compliance, and complete auditability. ## How smart redaction works AI Smart Redact processes documents through a four-stage pipeline. 1. **Input.** An integrating system submits a PDF. AI Smart Redact encrypts it immediately. 1. **Detect.** The detection engine identifies personally identifiable information (PII) using a hybrid of an AI model and a deterministic rules engine. 1. **Review.** A reviewer inspects, dismisses, or adds detections, and then approves the set before any redaction is applied. 1. **Redact.** AI Smart Redact creates a new PDF by copying only the visible, approved elements. Hidden content, metadata, and invisible layers don't carry over. ## Detection engine AI Smart Redact combines two complementary detection approaches: - **AI model.** A non-generative Named Entity Recognition (NER) model. It identifies context-dependent entities (people, organizations, addresses) and supports English, German, French, Italian, Spanish, Portuguese, and Dutch. The model works out of the box; no customer data is needed for training. It can't hallucinate or produce output beyond text in the document. - **Rules engine.** A deterministic pattern matcher for structured identifiers: credit card numbers, IBANs, account numbers, case IDs, and other domain-specific patterns. Each match is explainable, and checksum or format validation rejects false-positive matches. You can extend both: add new PII entity types through configuration, and add new patterns without retraining the model. For the full pipeline and per-method details, refer to [Detection](https://www.pdf-tools.com/docs/smart-redact/references/detection/). ## Key features AI Smart Redact provides: - **Self-hosted:** Deploy in your own infrastructure. License validation is offline. Runtime usage reporting connects to the Pdftools licensing server, or to an on-premise [License Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/) for air-gapped deployments. - **True redaction:** The output PDF contains only visible, approved elements. Hidden content, metadata, and invisible layers don't carry over. - **Human-in-the-Loop (HITL) review:** A reviewer approves every detection before redaction. - **Full audit trail:** OpenTelemetry integration provides per-job traceability. Every detection and redaction action is logged for compliance verification. ## Data handling ### File encryption AI Smart Redact encrypts each uploaded file at rest using AES-256-GCM with a unique per-file Data Encryption Key (DEK). The Manager doesn't persist DEK tokens; it returns each token to the integrating system, which holds it. The Orchestrator caches tokens temporarily for the human review workflow only; refer to [DEK token storage in the human review workflow](#dek-token-storage-in-the-human-review-workflow). Without the token, the encrypted file is cryptographically unreadable. ### DEK token storage in the human review workflow During human review, the Orchestrator caches each DEK token until the reviewer finishes. Two backends are available: | Backend | When to use | |---|---| | **Redis (recommended)** | Configure with `Redis__ConnectionString` on the Orchestrator. Deploy without persistence (no AOF, no RDB) so cached tokens are lost on restart, which is what guarantees crypto-erasure. | | **In-memory (fallback)** | Used automatically when `Redis__ConnectionString` is empty. Single-instance only; tokens don't survive a restart or scale across replicas. | ### Crypto-erasure Deleting a DEK token makes the corresponding file permanently unrecoverable, even if encrypted blobs remain in backup storage. This supports provable deletion in line with General Data Protection Regulation (GDPR) Art. 5(1)(e) and NIST SP 800-88. The following scenarios trigger crypto-erasure: | Scenario | Result | |---|---| | Client deletes the DEK token | File is immediately and permanently unrecoverable. | | DEK token time to live (TTL) expires | Server rejects further operations; file is unrecoverable. | | Client calls `DELETE /v1/files/{fileId}` | Encrypted blob deleted; token discarded. | :::info[Compliance coverage] The DEK token design addresses GDPR Art. 5(1)(b,c,e), Art. 30, Art. 32, Art. 35, and NIST SP 800-88. ## System requirements The following table lists the minimum RAM and CPU allocation per service container, with notes on what drives each figure: | Service | RAM | CPU | Notes | |---------|-----|-----|-------| | **Worker (CPU)** | 4 GB | 2 cores | The AI model loads ~2.9 GB into memory at startup. Detection pins one core at 100%. | | **Worker (GPU)** | 4 GB+ | 2 cores | GPU inference offloads compute, but the model still loads into RAM. VRAM requirements depend on the GPU. | | **Manager** | 1 GB | 2 cores | Baseline ~217 MB. Peaks during file encryption at about two times the file size per concurrent upload. | | **Orchestrator** | 1 GB | 2 cores | Similar profile to Manager (proxies uploads, manages sessions). | | **PostgreSQL** (per DB) | 512 MB | 1 core | Observed 44-73 MB under load. 512 MB provides headroom for query cache and connection state. | | **RabbitMQ** | 512 MB | 1 core | Lightweight for this workload. Increase if queue depths grow large (>10k messages). | | **Redis** | 256 MB | 0.5 core | Ephemeral session/token cache only (no persistence). | **Total minimum for the full stack (CPU mode):** ~8.5 GB RAM, 9.5 CPU cores (includes two PostgreSQL instances: one for Manager, one for Orchestrator). :::info[GPU acceleration] A CUDA-compatible GPU is optional but recommended for higher detection throughput at scale. For more details, refer to [Scale](https://www.pdf-tools.com/docs/smart-redact/guides/scale) and [Worker configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/worker). ### Containerization AI Smart Redact ships as Docker images and supports Docker Compose and Kubernetes deployments. For setup steps, review [Getting started](https://www.pdf-tools.com/docs/smart-redact/getting-started). ## Licensing AI Smart Redact is licensed per deployment. For setup, review [Licensing](https://www.pdf-tools.com/docs/licenses/products/smart-redact-license/). To get a license or discuss pricing, [contact sales](https://www.pdf-tools.com/contact/). --- ## Get started with AI Smart Redact Deploy AI Smart Redact using Docker Compose, then upload and redact your first document through the web application. The full stack includes the Manager API, a Worker for entity detection, the Orchestrator for authentication and job management, the Human-in-the-Loop (HITL) web application for browser-based review, and two PostgreSQL databases. ## Get a trial license key To try AI Smart Redact, you must obtain a license key. To get the AI Smart Redact evaluation license key for free, follow these steps: 1. [Sign up](https://portal.pdf-tools.com/account/sign-up) or log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. On the **Products** page, next to AI Smart Redact, click **Get started** or **See product**. 1. Next to the **AI Smart Redact Trial**, click **Copy** to copy the license key. The free trial license key has the following limitations: - The redacted files contain a watermark. - The license key expires after 90 days. **note: The trial license key is valid for 90 days starting at UTC time. The Pdftools Portal indicates the validity period starting at 89 days (as the consumption of the first day already started). This period may slightly vary depending on your time zone relative to UTC.** To get a full license key for production use, [contact sales](https://www.pdf-tools.com/contact/). ## Prerequisites - Docker and Docker Compose v2+ are installed. - You have a valid **AI Smart Redact license key**. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/) to retrieve your license key. - **On Windows:** the helper script requires bash. Use one of: - **WSL2** (recommended): a full Linux environment. Docker Desktop integrates with WSL2 natively, so `docker` commands work without extra configuration. [Install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). - **Git Bash**: bundled with [Git for Windows](https://git-scm.com/download/win). Works for all Docker-based scripts, provided Docker Desktop is running and `python3` is on `PATH` (needed by the curl API examples). ## Clone the samples repository Clone the samples repository and navigate to its root directory: ```bash git clone https://github.com/pdf-tools/smart-redact-samples.git cd smart-redact-samples ``` ## Set up the environment Run the setup command with your license key: ```bash ./smart-redact.sh setup --license-key "" ``` Replace `` with your AI Smart Redact license key from [Get a trial license key](#get-a-trial-license-key). This creates `docker-compose/cpu/.env` with your license key and auto-generated `ENCRYPTION_KEY` and `ORCHESTRATOR_JWT_SECRET`. No manual key generation is needed. **info: All three services (Manager, Worker, Orchestrator) validate the license key. The Worker fails to start without a license key. The Manager and Orchestrator start normally but reject API requests with HTTP 403 if the key is missing or invalid.** ## Start the services 1. Start all services and wait for health checks to pass: ```bash ./smart-redact.sh up ``` 1. Verify all services are healthy: ```bash ./smart-redact.sh health ``` Once ready, the following endpoints are available: - **HITL web application:** http://localhost:3000 - **Manager API (Swagger):** http://localhost:9982/swagger - **Orchestrator API (Swagger):** http://localhost:9983/swagger ## Redact your first document The repository includes a sample PDF under `samples/` that you can use to test the workflow. 1. Open the HITL web application at [http://localhost:3000](http://localhost:3000). 1. Log in with the default credentials (email: `admin@example.com`, password: `Admin@1234!Tmp`). 1. Change the default password when prompted. Never use the seeded credentials in production. For the full first log-in flow and password requirements, refer to [Authenticate with AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/authentication). 1. Upload a PDF document containing sensitive data. You can use the included sample: `samples/Sample Document — AI Smart Redact.pdf`. 1. Review the detected entities in the document viewer. Each entity is highlighted with its type label. 1. Add, remove, or adjust detections as needed, then redact the document. 1. Download the redacted PDF. For details on the web application workflow, refer to [HITL web application](https://www.pdf-tools.com/docs/smart-redact/guides/hitl-web-application). **tip: For API-only usage without the web UI, use the `minimal` variant:** ```bash ./smart-redact.sh setup --license-key "" --variant minimal ./smart-redact.sh up --variant minimal ``` Refer to the [API reference](https://www.pdf-tools.com/docs/smart-redact/references/api/) for endpoint documentation. ## Start with GPU support For GPU-accelerated entity detection, run setup and start with the `gpu` variant: ```bash ./smart-redact.sh setup --license-key "" --variant gpu ./smart-redact.sh up --variant gpu ``` For NVIDIA Container Toolkit installation and additional GPU configuration, refer to [GPU deployment](https://www.pdf-tools.com/docs/smart-redact/guides/configuration#gpu-deployment) in the configuration guide. ## Stop the services Stop and remove containers: ```bash ./smart-redact.sh down ``` Stop and remove containers including all data volumes: ```bash ./smart-redact.sh clean --volumes ``` To also remove the downloaded Docker images: ```bash ./smart-redact.sh clean --all ``` ## Next steps - [Configure AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/configuration) for production settings (S3 storage, encryption, scaling). - [Scale AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/scale) with multiple Workers and GPU acceleration. - [Set up observability](https://www.pdf-tools.com/docs/smart-redact/guides/observability) with OpenTelemetry and Grafana. - Review the [Architecture](https://www.pdf-tools.com/docs/smart-redact/references/architecture) to understand how the subsystems connect. --- ## Guides(Guides) These guides walk you through the operational tasks involved in running AI Smart Redact in development and production: configuring services, scaling Workers horizontally and vertically, setting up authentication, monitoring jobs, and updating between versions. Each guide assumes that you've already deployed the stack with Docker Compose by following [Get started with AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/getting-started/). --- ## Authenticate with AI Smart Redact The Orchestrator API uses JWT bearer tokens for authentication. This guide covers the authentication flow, first log-in setup, API key authentication for automated workflows, and command-line examples. ## Overview Two tokens are involved in the authentication flow: | Token | Lifetime | Purpose | |-------|----------|---------| | **Access token** | 15 minutes | Short-lived JWT sent as `Authorization: Bearer ` on every request. | | **Refresh token** | 30 days | Long-lived opaque token stored as an HttpOnly cookie scoped to `/v1/auth`. Used to obtain new access tokens without re-entering credentials. | All endpoints require an access token except `POST /v1/auth/login` and `POST /v1/auth/refresh`. **info: The refresh token cookie is scoped to `/v1/auth`. The browser only sends this cookie on requests to `/v1/auth/*` paths (such as `/v1/auth/refresh`). It isn't sent on other API paths like `/v1/users`. If your refresh request isn't including the cookie, verify the request URL starts with `/v1/auth`.** ## Default credentials A seeded admin account is created automatically on first startup: | Field | Value | |-------|-------| | Email | `admin@example.com` | | Password | `Admin@1234!Tmp` | The account has the `PasswordResetRequired` flag set. Change this password immediately after the first log in. ## First log-in flow 1. Call `POST /v1/auth/login` with the default credentials. 1. The response contains an access token with a `password_reset_required` claim. 1. Call `POST /v1/auth/reset-password` with the token from step 2 to set a new password. 1. Use the new access token returned by step 3 for all subsequent requests. **info: The password reset isn't enforced. You can use other endpoints without resetting first. However, changing the default password immediately is strongly recommended.** ## JWT configuration **Setting used (Orchestrator):** `Jwt.SecretKey`. Generate the value with the command below. The Orchestrator signs JWT tokens with an HMAC-SHA256 secret key. Generate one and set it before starting the Orchestrator: ```bash openssl rand -base64 64 | tr -d '\n' ``` ```yaml environment: Jwt__SecretKey: "" ``` For the full settings catalog (`SecretKey`, `ExpirationMinutes`, `RefreshTokenExpirationDays`), refer to [Orchestrator > JWT](https://www.pdf-tools.com/docs/smart-redact/references/configuration/orchestrator#jwt). ## Command-line usage The following examples use `curl`. Save the Orchestrator base URL to a variable: ```bash BASE_URL=http://localhost:9983 ``` ### Log in ```bash curl -s -c cookies.txt -X POST "$BASE_URL/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{"login": "admin@example.com", "password": "Admin@1234!Tmp"}' | tee login_response.json ``` Extract the token: ```bash TOKEN=$(grep -o '"token":"[^"]*"' login_response.json | cut -d'"' -f4) ``` ### Reset password (first log in) ```bash curl -s -c cookies.txt -b cookies.txt -X POST "$BASE_URL/v1/auth/reset-password" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"newPassword": "MySecurePassword1!"}' | tee reset_response.json TOKEN=$(grep -o '"token":"[^"]*"' reset_response.json | cut -d'"' -f4) ``` ### Call a protected endpoint ```bash curl -s -X GET "$BASE_URL/v1/users" \ -H "Authorization: Bearer $TOKEN" ``` ### Refresh the access token When the access token expires, use the saved cookie to refresh it: ```bash curl -s -c cookies.txt -b cookies.txt -X POST "$BASE_URL/v1/auth/refresh" | tee refresh_response.json TOKEN=$(grep -o '"token":"[^"]*"' refresh_response.json | cut -d'"' -f4) ``` The refresh token is automatically rotated. The cookie file is updated with the new value. ### Change password ```bash curl -s -X POST "$BASE_URL/v1/auth/change-password" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"currentPassword": "OldPassword1!", "newPassword": "NewPassword1!"}' ``` All existing refresh tokens are revoked and a new access token is returned. ### Log out ```bash curl -s -b cookies.txt -X POST "$BASE_URL/v1/auth/logout" \ -H "Authorization: Bearer $TOKEN" ``` ## API key authentication API keys provide non-interactive authentication for automated scripts and integrations. Unlike JWT, API keys don't require a log-in flow. Send the key directly in a request header. ### How API keys work 1. An admin creates an API key for a specific user through `POST /v1/api-keys`. 1. The raw key (for example, `pdft_AbCdEf...`) is returned **once** in the response. It can't be retrieved later. 1. Include the key in every request using the `X-Api-Key` header. 1. The server hashes the key, looks it up in the database, and authenticates the request as the linked user. ### Key details | Property | Value | |----------|-------| | **Format** | `pdft_` prefix + 32 cryptographically random bytes (base64url, ~48 characters total) | | **Storage** | Only the SHA-256 hash is stored in the database | | **Expiration** | Required when creating, maximum 12 months | | **Scope** | Jobs endpoints only (`POST /v1/jobs`, `GET /v1/jobs`, `GET /v1/jobs/{id}`, `POST /v1/jobs/{id}/redaction`, `GET /v1/jobs/{id}/files/{fileType}`) | ### Create an API key (admin) ```bash curl -s -X POST "$BASE_URL/v1/api-keys" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{ "name": "CI Pipeline Key", "userId": "", "expiresAt": "2027-01-01T00:00:00Z" }' ``` Replace `` with the ID of the user the key authenticates as. Save the raw `key` field from the response immediately. It won't be shown again. ### Use an API key ```bash # Upload a file curl -s -X POST "$BASE_URL/v1/jobs" \ -H "X-Api-Key: pdft_your_key_here" \ -F "file=@document.pdf" # List jobs curl -s -X GET "$BASE_URL/v1/jobs" \ -H "X-Api-Key: pdft_your_key_here" # Download redacted file curl -s -X GET "$BASE_URL/v1/jobs//files/redactedPdf" \ -H "X-Api-Key: pdft_your_key_here" \ --output redacted.pdf ``` Replace `` with the job identifier returned when the redaction job was created. ### Revoke an API key (admin) ```bash curl -s -X POST "$BASE_URL/v1/api-keys//revoke" \ -H "Authorization: Bearer $TOKEN" ``` Replace `` with the API key's ID (returned by `GET /v1/api-keys`). Revocation is immediate. The key is rejected on the next request. ## Swagger UI The Orchestrator Swagger UI is available at `http://localhost:9983/swagger`. To authenticate in Swagger: 1. Call `POST /v1/auth/login` to get an access token. 1. Click the **Authorize** button (top right). 1. In the `Bearer (ApiKey)` field, enter: `Bearer ` (include the `Bearer` prefix). 1. Click **Authorize**, then **Close**. **info: After resetting or changing your password, re-authorize with the new token returned by the response.** ## Reset the admin user If you're locked out, delete the admin account from the database. It's re-seeded with the default credentials on the next startup. The seeded admin's username is `admin` (separate from the email address). ### PostgreSQL (Docker) ```bash docker exec -it smart-redact-orchestrator-db \ psql -U smartredact -d smartredact \ -c "DELETE FROM \"AspNetUsers\" WHERE \"UserName\" = 'admin';" docker compose restart smart-redact-orchestrator ``` --- ## Configure AI Smart Redact AI Smart Redact runs as three services: **Manager**, **Worker**, and **Orchestrator**. This guide covers operational tasks for configuring them, including encryption-key generation, key rotation, file storage backends, and GPU deployment. For the complete settings catalog per service, refer to: - [Manager configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/manager) - [Worker configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/worker) - [Orchestrator configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/orchestrator) ## Apply configuration changes Each service is configured through environment variables on its Docker container, using the `Section__Field` (double underscore) naming convention. For example: ```bash Encryption__EncryptionKey= Database__DatabaseType=PostgreSql ``` Settings are read once at container startup, so changing a variable requires recreating the container. The encryption key is the only setting that hot-reloads (refer to [Key rotation](#key-rotation)). The procedures below show settings in `appsettings.json` form for clarity; the equivalent environment-variable form works the same way. For the full naming convention, refer to [Configuration reference > Environment variables](https://www.pdf-tools.com/docs/smart-redact/references/configuration/#environment-variables). ### Mount a custom appsettings.json As an alternative to environment variables, mount your own `appsettings.json` into the container at `/app/appsettings.json`: ```yaml services: smart-redact-manager: volumes: - ./manager-appsettings.json:/app/appsettings.json:ro ``` Mounting the file is what enables hot-reload of the encryption key (refer to [Key rotation](#key-rotation)). All other settings still require recreating the container. ## Tune chunk size for performance **Setting used (Worker):** `Inference.MaxChunkSize`. The chunk size affects the trade-off between detection accuracy and processing speed: | MaxChunkSize | Use case | Trade-off | |--------------|----------|-----------| | 384-512 | High accuracy | Maximum context, slower processing | | 256 | Balanced (default) | Good accuracy and speed | | 128-256 | High throughput | Faster processing, less context per chunk | ## GPU deployment A separate Docker Compose file is provided for GPU deployments. It uses a GPU-specific Dockerfile and reserves NVIDIA GPU devices: Use the GPU variant from the [samples repository](https://github.com/pdf-tools/smart-redact-samples): ```bash cd smart-redact-samples/docker-compose/gpu cp .env.example .env # Fill in your license key and secrets docker compose up -d ``` The GPU Compose file uses the `-cuda` Worker image (`pdftoolsag/smart-redact-worker:latest-cuda`) with NVIDIA device reservations. The [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) must be installed on the host. For image variants, throughput trade-offs, and inference tuning, refer to [Scale > Vertical scaling](https://www.pdf-tools.com/docs/smart-redact/guides/scale#vertical-scaling-optimize-a-single-worker). ## Produce an encryption key **Setting used (Manager + Worker):** `Encryption.EncryptionKey`. Generate the value with one of the commands below. The encryption key must be exactly 32 bytes (256 bits), Base64-encoded. Both the Manager and Worker must use the same key. ```bash # Using OpenSSL (recommended) openssl rand -base64 32 # Using Python python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())" ``` **warning: Store the encryption key in a secret manager for production deployments. Don't commit it to `appsettings.json` in a shared repository.** ## How encryption works The system uses a two-tier encryption model for GDPR-compliant crypto-erasure: - **KEK** (Key Encryption Key): Stored in configuration. Encrypts per-file DEKs in tokens. - **DEK** (Data Encryption Key): Per-file random key, encrypted in a client-held token. Each file (uploaded PDF, output FDF, redacted PDF) has its own unique DEK token. Discarding a token makes that specific file cryptographically inaccessible (crypto-erasure). ### Key rotation Rotating the KEK invalidates all existing DEK tokens, because tokens encrypted with the old KEK can't be decrypted with the new one. The KEK is the only setting that supports hot-reload, so you can rotate it without restarting the service. However, you still need to drain in-flight work first to avoid stranding files. To rotate safely: 1. Stop accepting new jobs. 1. Wait for in-flight jobs to complete (tokens expire based on `DekTokenTtlMinutes`). 1. Verify the storage is empty (all files deleted). 1. Update the encryption key. The service picks up the new key automatically. 1. Resume accepting jobs. All other configuration settings are read once at startup. To change them, recreate the container. ## AWS S3 file storage **Settings used (Manager + Worker):** `FileStorage.FileStorageType`, `FileStorage.ConnectionString`. Store files in an S3 bucket instead of the local file system. Configure both the Manager and Worker: ```json { "FileStorage": { "FileStorageType": "AwsS3", "ConnectionString": "my-bucket-name;eu-west-1" } } ``` The connection string format is `bucket-name;region`. The service uses the AWS default credential chain (SSO, IAM roles, environment variables). Before starting the services, authenticate with AWS: ```bash aws sso login aws sts get-caller-identity ``` The IAM role or user must have `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, and `s3:ListBucket` permissions on the bucket. ## MinIO file storage **Settings used (Manager + Worker):** `FileStorage.FileStorageType`, `FileStorage.ConnectionString`. Store files in a self-hosted MinIO instance (S3-compatible). Configure both the Manager and Worker: ```json { "FileStorage": { "FileStorageType": "MinIO", "ConnectionString": "minio.s3://keyId=;key=;bucket=;serviceUrl=" } } ``` Replace the following: - ``: The name of the MinIO bucket that holds AI Smart Redact files. - ``: The MinIO server URL, including scheme and port. For example: `http://minio:9000`. - ``: The MinIO access key. - ``: The MinIO secret key. You can also use the `aws.s3://` prefix with a `serviceUrl=` parameter, which is automatically converted to the MinIO format. ## Docker Compose reference These are the key environment variables for a production Docker Compose deployment: ```yaml services: smart-redact-manager: environment: Database__DatabaseType: "PostgreSql" Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-manager-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;" FileStorage__FileStorageType: "HostFileSystem" FileStorage__FilesDirectoryPath: "/app/storage_folder" Encryption__EncryptionKey: "${ENCRYPTION_KEY}" Encryption__DekTokenTtlMinutes: 1440 ServiceCommunication__ConnectionString: "http://smart-redact-worker:4885/" Licensing__LicenseKey: "${PDFTOOLS_LICENSE_KEY}" OTEL_EXPORTER_OTLP_ENDPOINT: "${OTEL_EXPORTER_OTLP_ENDPOINT:-}" volumes: - storage:/app/storage_folder - logs:/app/logs smart-redact-orchestrator: environment: ManagerApi__BaseUrl: "http://smart-redact-manager:9982/" ManagerApi__PollingIntervalSeconds: 3 Database__DatabaseType: "PostgreSql" Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-orchestrator-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;" Jwt__SecretKey: "${ORCHESTRATOR_JWT_SECRET}" Licensing__LicenseKey: "${PDFTOOLS_LICENSE_KEY}" ``` --- ## Set up the HITL web application The Human-in-the-Loop (HITL) web application provides a browser-based interface for reviewing AI-detected entities. Approve or modify detections before redaction. It connects to the Orchestrator API for job management and authentication. ## Architecture The HITL web application is a lightweight frontend that communicates with the Orchestrator service. The Orchestrator manages user sessions, jobs, and the connection to the Manager API. ```mermaid flowchart LR Browser["Browser User"] Client["API Client(curl / Python / C#)"] HITL["HITL web appport 3000"] Orchestrator["Orchestrator APIport 9983User mgmt, JWT auth"] Manager["Manager APIport 9982Files, Jobs, Orchestration"] Worker["Worker APIport 4885 (internal)PII detection, redaction"] OrchDB[("Orchestrator DBPostgreSQL")] ManagerDB[("Manager DBPostgreSQL")] Browser -- HTTP --> HITL Client -- HTTP --> Orchestrator HITL -- HTTP --> Orchestrator Orchestrator -- HTTP --> Manager Manager -- HTTP --> Worker Orchestrator --- OrchDB Manager --- ManagerDB ``` ## Set up with Docker Compose The standard Docker Compose deployment includes the HITL web application: ```yaml services: smart-redact-hitl-web: container_name: smart-redact-hitl-web ports: - "3000:8080" environment: ORCHESTRATOR_HOST: "smart-redact-orchestrator" VITE_API_URL: "${HITL_ORCHESTRATOR_URL:-http://localhost:9983}" networks: - smart-redact-network depends_on: - smart-redact-orchestrator ``` | Setting | Default | Description | |---------|---------|-------------| | `ORCHESTRATOR_HOST` | (required) | Hostname of the Orchestrator service. In Docker Compose, use the service name (`smart-redact-orchestrator`). | | `VITE_API_URL` | `http://localhost:9983` | URL for the browser to reach the Orchestrator API. Override with the `HITL_ORCHESTRATOR_URL` environment variable. | | Port mapping | `3000:8080` | The web application listens on port 8080 inside the container, mapped to port 3000 on the host. | After starting the services with `docker compose up -d`, access the web application at: ``` http://localhost:3000 ``` ## Log in The HITL web application uses the Orchestrator's authentication system. Log in with the seeded admin credentials and change the password when prompted. For the default values, password-change flow, user management, and API keys, refer to [Authenticate with AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/authentication). ## Redaction workflow The HITL web application lets you review and adjust AI-detected redactions before applying them to documents. ### Document management The main view displays a list of all documents with their current status. Documents can be in one of the following states: - **Processing**: AI Smart Redact is detecting PII in the document. - **Ready for review**: PII detection is complete and the document is ready for review. - **Redacted**: The document has been redacted and is available for download. - **Expired**: The document wasn't reviewed before its configured retention period elapsed and is no longer accessible. The default retention period is 24 hours. #### Upload documents Upload documents in two ways: - **Manual upload**: Click **Upload files** to select and upload documents through the web interface. - **API upload**: Upload documents programmatically using the AI Smart Redact API. After upload, the document enters the **Processing** state while AI Smart Redact detects PII. After processing completes, the status changes to **Ready for review**. #### Filter and search Use the filter options to narrow the document list: - Search by document name. - Filter by status (All statuses, Ready for review, Redacted, Processing). - Filter by uploader. - Filter by reviewer. ### Review redactions Click a document with **Ready for review** status to open the review interface. The review interface has two panels: - **Left panel**: Hierarchical list of detected PII categories and individual items marked for redaction. - **Right panel**: Document preview with highlighted redactions. #### Manage redactions Select or clear categories and individual items in the left panel: - **Category level**: Select or clear entire categories (for example, Personal & Social, Banking & Financial). - **Item level**: Select or clear individual detected items (for example, specific email addresses or phone numbers). To add new redactions not detected by the AI, use the annotation tools in the document preview. #### Preview redactions The **Preview redaction** toggle simulates how the document appears after redaction. When enabled, detected PII appears as black bars, showing the final redacted output. ### Apply redactions After reviewing and adjusting the redactions, click **Apply redaction** to permanently redact the document. The document status changes to **Redacted** and appears in the document list with the updated status. #### Download redacted documents Download redacted documents in two ways: - **Web interface**: Click the download icon in the Actions column. - **API**: Retrieve the redacted document programmatically using the AI Smart Redact API. ## Health check The HITL web application exposes a health check endpoint: ```bash curl http://localhost:3000/ ``` The Docker Compose configuration includes a built-in health check: ```yaml healthcheck: test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/"] interval: 10s timeout: 5s start_period: 10s retries: 3 ``` --- ## Monitor AI Smart Redact Monitor AI Smart Redact using health check endpoints, log files, and the RabbitMQ management interface. This guide covers the monitoring capabilities of all three services. ## Health check endpoints Each service exposes health check endpoints for monitoring, load balancer probes, and container orchestration. | Service | Endpoint | Default port | |---------|----------|-------------| | Manager | `http://localhost:9982/healthz/ready` | 9982 | | Worker | `http://localhost:4885/healthz/ready` (internal) | 4885 | | Orchestrator | `http://localhost:9983/healthz/ready` | 9983 | The Worker port (`4885`) is internal to the Docker network in the default deployment and isn't exposed to the host. To check Worker health from the host, use: ```bash docker compose exec smart-redact-worker curl http://localhost:4885/healthz/ready ``` All services also expose two additional health endpoints: | Endpoint | Purpose | |----------|---------| | `/healthz/startup` | Startup probe. Returns 200 once the service has finished initialization. | | `/healthz/live` | Liveness probe. Returns 200 if the service process is running and not deadlocked. | | `/healthz/ready` | Readiness probe. Returns 200 if the service is ready to accept traffic. | For Kubernetes deployments, use `/healthz/live` for liveness probes and `/healthz/ready` for readiness probes. Use `/healthz/startup` for startup probes to avoid premature liveness failures during model loading. ### License validation Each service validates the license key, but the behavior differs: | Service | Behavior on invalid or missing license | |---------|---------------------------------------| | **Manager** | Starts normally, but rejects API requests with HTTP 403. | | **Orchestrator** | Starts normally, but rejects API requests with HTTP 403. | | **Worker** | Fails to start. Check Worker logs if the container exits immediately after startup. | ### Health states The Manager's health endpoint reports three states: | State | HTTP status | Condition | |-------|-------------|-----------| | **Healthy** | 200 | Pending job count is below the threshold. | | **Degraded** | 200 | Pending job count exceeds the `HealthCheckPendingJobThreshold`. The service is still accepting requests, but signals saturation to monitoring tools. | | **Unhealthy** | 503 | The database is unreachable. | ### Configure backpressure-aware health checks Enable backpressure monitoring on the Manager to signal saturation to load balancers and orchestrators like Kubernetes: ```yaml environment: ServiceCommunication__HealthCheckPendingJobThreshold: 15 ServiceCommunication__BackpressureMonitorIntervalSeconds: 5 ``` | Setting | Default | Description | |---------|---------|-------------| | `HealthCheckPendingJobThreshold` | `null` (disabled) | Pending job count above which `/healthz/ready` returns `Degraded`. | | `BackpressureMonitorIntervalSeconds` | `5` | How often (in seconds) the service polls the pending job count from the database. | ## Admission control Limit the number of concurrent pending jobs to prevent unbounded queue growth. When the limit is reached, new requests are rejected with HTTP 429 (Too Many Requests). ```yaml environment: ServiceCommunication__MaxPendingJobs: 20 ``` | Setting | Default | Description | |---------|---------|-------------| | `MaxPendingJobs` | `null` (disabled) | Maximum in-progress jobs before rejecting new requests. Must be a positive integer when set. | **tip: Scale `MaxPendingJobs` proportionally to the number of Workers: `2-3x * (num_workers * DetectionConcurrencyLimit)`.** ## Log files All services write structured logs using Serilog. In the samples repository Docker Compose files, logs are written to a named volume: ```yaml volumes: - logs:/app/logs ``` Configure the log file path and retention in `appsettings.json`: ```json { "LogFilePath": "/app/logs/smart-redact-manager-log.txt", "LogRetentionDays": 7 } ``` ## OpenTelemetry AI Smart Redact supports OpenTelemetry for exporting traces, logs, and metrics to your monitoring backend. Telemetry is disabled by default and has zero runtime overhead when not configured. Enable telemetry by setting the OTLP endpoint on the Manager and Worker services: ```yaml environment: OTEL_EXPORTER_OTLP_ENDPOINT: http://your-collector:4317 OTEL_EXPORTER_OTLP_PROTOCOL: grpc ``` | Signal | What it tells you | |--------|-------------------| | **Traces** | How long each job took, where time was spent, whether it succeeded or failed. | | **Logs** | Structured application logs with trace correlation (`TraceId`/`SpanId`). | | **Metrics** | API request rates, response latencies, error rates, and job counters. | The service is compatible with any OTLP-capable backend: Grafana, Seq, Jaeger, Datadog, Elastic APM, or Azure Monitor. ### Grafana dashboard AI Smart Redact exports telemetry through OpenTelemetry, which you can connect to Grafana to visualize jobs, detection metrics, HTTP server activity, and recent operations. For span attributes, custom metrics, export defaults, and example queries, refer to [Set up observability for AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/observability). ## RabbitMQ management UI When using RabbitMQ for service communication, the management UI provides visibility into queue depths, message rates, and consumer status. - **URL**: `http://localhost:15672` - **Default credentials**: `guest` / `guest` ### Key queues to monitor | Queue | Purpose | |-------|---------| | `worker-detection-queue` | Detection jobs sent from Manager to Workers | | `worker-redaction-queue` | Redaction jobs sent from Manager to Workers | | `manager-queue` | Job results sent from Workers back to the Manager | | `worker-detection-queue_error` | Failed detection messages (after all retries exhausted) | | `worker-redaction-queue_error` | Failed redaction messages | | `manager-queue_error` | Failed result messages from Workers to the Manager | A growing error queue indicates recurring infrastructure issues. Check Worker logs for the root cause. ## Troubleshooting ### Worker job stuck in `InProgress` 1. Check Worker logs for errors. 1. Check Manager logs for `S-FAULT` or `Send timeout`. These indicate the broker rejected the message or the send timed out. 1. Check the RabbitMQ management UI. Look for the message in an error queue. 1. If the Worker restarted, the message should have been redelivered automatically. 1. If `MaxPendingJobs` is configured and the limit was reached, the job is deleted (not stuck) and the client receives HTTP 429. ### Worker not consuming messages 1. Verify `ServiceCommunicationType` matches on both Manager and Worker (both must use `RabbitMQ`). 1. Check the broker is healthy: ```bash docker exec rabbitmq rabbitmq-diagnostics -q check_port_connectivity ``` 1. Verify the concurrency limit isn't set to 0: ```yaml ServiceCommunication__DetectionConcurrencyLimit: 1 ``` ### Out-of-memory during file upload If an upload triggers an out-of-memory condition during encryption, the service returns HTTP 503 with `"The server does not have enough resources to process this request. Try reducing file size or concurrent uploads."` The service stays healthy and continues processing subsequent requests. To prevent this, tune `MaxFileSizeBytes` and `MaxConcurrentConnections` together. --- ## Set up observability for AI Smart Redact AI Smart Redact includes built-in observability through OpenTelemetry, giving you visibility into job processing, errors, and performance. Telemetry is disabled by default and has zero runtime overhead when not configured. ## Overview The service exports three types of telemetry data through the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otel/protocol/): | Signal | What it tells you | |--------|-------------------| | **Traces** | How long each job took, where time was spent, whether it succeeded or failed. | | **Logs** | Structured application logs with trace correlation (`TraceId`/`SpanId`). | | **Metrics** | API request rates, response latencies, error rates, and job counters. | The service is compatible with any OTLP-capable backend: Grafana, Seq, Jaeger, Datadog, Elastic APM, Azure Monitor, or a self-hosted OpenTelemetry Collector. ## Enable telemetry Set these environment variables on the Manager and Worker services: | Variable | Required | Description | |----------|----------|-------------| | `OTEL_EXPORTER_OTLP_ENDPOINT` | Yes | Your OTLP collector endpoint. Setting this enables telemetry. | | `OTEL_EXPORTER_OTLP_PROTOCOL` | No | Transport protocol: `grpc` (default) or `http/protobuf`. Use `http/protobuf` for backends like Seq that require HTTP. | | `OTEL_SERVICE_NAME` | No | Overrides the default service name in telemetry data. Defaults to `SmartRedact.Manager` or `SmartRedact.Worker`. Set this if you prefer a different name in your telemetry backend. | **info: The default service names (`SmartRedact.Manager`, `SmartRedact.Worker`) are set by the application. The example queries in this guide use these defaults. If you override `OTEL_SERVICE_NAME`, adjust the queries accordingly.** Docker Compose example (gRPC backend): ```yaml services: smart-redact-manager: environment: OTEL_EXPORTER_OTLP_ENDPOINT: http://your-collector:4317 OTEL_EXPORTER_OTLP_PROTOCOL: grpc smart-redact-worker: environment: OTEL_EXPORTER_OTLP_ENDPOINT: http://your-collector:4317 OTEL_EXPORTER_OTLP_PROTOCOL: grpc ``` ## Export defaults Telemetry data is batched and buffered before export. These are the OpenTelemetry SDK defaults. No configuration is needed unless you want to tune them. ### Traces (Batch Span Processor) | Variable | Default | Description | |----------|---------|-------------| | `OTEL_BSP_SCHEDULE_DELAY` | 5000 ms | How often batches are flushed. | | `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | 512 | Maximum spans per export. | | `OTEL_BSP_MAX_QUEUE_SIZE` | 2048 | Maximum spans queued before dropping. | | `OTEL_BSP_EXPORT_TIMEOUT` | 30000 ms | Timeout per export call. | ### Logs (Batch Log Record Processor) | Variable | Default | Description | |----------|---------|-------------| | `OTEL_BLRP_SCHEDULE_DELAY` | 1000 ms | How often batches are flushed. | | `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE` | 512 | Maximum log records per export. | | `OTEL_BLRP_MAX_QUEUE_SIZE` | 2048 | Maximum log records queued before dropping. | | `OTEL_BLRP_EXPORT_TIMEOUT` | 30000 ms | Timeout per export call. | ### Metrics (Periodic Metric Reader) | Variable | Default | Description | |----------|---------|-------------| | `OTEL_METRIC_EXPORT_INTERVAL` | 60000 ms | How often metrics are exported. | | `OTEL_METRIC_EXPORT_TIMEOUT` | 30000 ms | Timeout per export call. | In practice: spans are sent every 5 seconds (or when 512 accumulate), logs every 1 second, and metrics every 60 seconds. ## Job processing traces Every detection and redaction job produces a trace span on the Worker service. Each span captures: - **Job identity**: job ID, file ID, job type (detection or redaction). - **Status**: finished or error, with failure reason on errors. - **Timing**: start time, duration, end time. - **Job metrics**: page count, file size, entity counts (depending on job type). The Manager enriches its consumer spans with job identity tags, so you can trace the full flow from Manager to Worker and back. Application logs include `TraceId` and `SpanId` fields, letting you jump from a log entry directly to its trace. ## Span attributes reference These attributes are set on Worker job processing spans: | Attribute | Type | Description | Example | |-----------|------|-------------|---------| | `job.id` | string | Unique job identifier | `a1b2c3d4-e5f6-...` | | `job.type` | string | `detection` or `redaction` | `detection` | | `job.file.id` | string | Primary input file identifier | `e5f6g7h8-...` | | `job.status` | string | Final status: `Finished` or `Error` | `Finished` | | `failure.reason` | string | Exception type on failure (absent on success) | `DekTokenValidationException` | | `input.file.pages` | int | Input PDF page count (detection only) | `12` | | `input.file.size_bytes` | long | Input PDF size in bytes (detection only) | `524288` | | `input.entities.count` | int | Entities submitted for redaction (redaction only) | `35` | | `output.entities.count` | int | Detected entity count (detection only) | `42` | | `output.file.size_bytes` | long | Redacted PDF size in bytes (redaction only) | `498000` | ## Custom metrics reference These Prometheus counters are exported through OTLP and tagged with `job.type` (detection/redaction) and `job.status` (Finished/Error): | Metric name | Extra tags | Description | |-------------|------------|-------------| | `jobs.completed` | (none) | Jobs completed (detection + redaction). | | `detection.entities.detected` | `entity.type` | Total entities detected, broken down by label. | | `detection.pages.processed` | (none) | Total pages processed across detection jobs. | | `licensing.pages.consumed` | (none) | Total pages reported for license consumption. | ## Useful queries These examples use Grafana's TraceQL and LogQL query languages. Find all job spans for a specific job: ``` {span.job.id = "your-job-id-here"} ``` Find all failed jobs: ``` {span.job.status = "Error"} ``` Find failed detection jobs: ``` {span.job.status = "Error" && span.job.type = "detection"} ``` List recent detection results (log-based): ``` {service_name="SmartRedact.Worker"} |= "DetectionResultEvent" ``` Find log events for a specific file: ``` {service_name="SmartRedact.Worker"} |= "ResultEvent" | json | FileId = "your-file-id-here" ``` --- ## Scale AI Smart Redact AI Smart Redact uses a **Manager-Worker architecture**: - The **Manager** handles the client-facing API, job orchestration, and file management. - **Workers** perform entity detection and PDF redaction. - The **Orchestrator** powers the Human-in-the-Loop (HITL) web application on top. ```mermaid flowchart TB subgraph Clients["Clients"] C1["Client App"] C2["HITL web app\nPort 3000"] end subgraph Orchestrator["Orchestrator · Port 9983"] OAPI["REST API + JWT Auth"] ODB[("Database")] end subgraph SmartRedact["Manager-Worker"] subgraph Manager["Manager · Port 9982"] MAPI["REST API"] MDB[("Database")] end Worker["Worker · Port 4885 (internal)"] FS[("File Storage")] end C1 --> Manager C2 --> Orchestrator Orchestrator --> Manager OAPI --- ODB MAPI --- MDB Manager -->|"HTTP · REST"| Worker Manager --- FS Worker --- FS style Clients fill:#f0f4ff,stroke:#dbe4f0,color:#334155 style Orchestrator fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Worker fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ## Minimal setup The minimal deployment uses a single Manager with SQLite and a single Worker, connected through REST. No message broker, no PostgreSQL. This setup is suitable for testing, evaluation, and low-traffic workloads. ```mermaid flowchart LR HITL["HITL web app\nPort 3000"] subgraph Orchestrator["Orchestrator · Port 9983"] OAPI["REST API + JWT Auth"] ODB[("Database")] end subgraph SmartRedact["Manager-Worker"] subgraph Manager["Manager · Port 9982"] API["REST API"] MDB[("Database")] end Worker["Worker · Port 4885"] FS[("Local File\nStorage")] end HITL --> Orchestrator Orchestrator --> Manager Manager -->|"HTTP · REST"| Worker Manager --- FS Worker --- FS style Orchestrator fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Worker fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ```yaml # Manager environment: Database__DatabaseType: "SqlLite" ServiceCommunication__ServiceCommunicationType: "Rest" ServiceCommunication__ConnectionString: "http://smart-redact-worker:4885/" FileStorage__FileStorageType: "HostFileSystem" FileStorage__FilesDirectoryPath: "/app/storage_folder" ``` To scale beyond a single Worker, choose a communication transport. ## Communication transports The Manager and Worker communicate using one of two transports. The transport determines how horizontal scaling works. Two complementary approaches scale AI Smart Redact: - **Horizontal scaling**: Add more Worker instances to increase throughput linearly. Each Worker loads its own AI model and operates independently. - **Vertical scaling**: Optimize throughput within a single Worker using GPU acceleration and batch inference tuning. ### REST transport In REST mode, the Manager calls the Worker directly over HTTP. No message broker is needed. To scale horizontally with REST, place a load balancer in front of multiple Worker instances. ```mermaid flowchart LR subgraph SmartRedact["Manager-Worker"] subgraph Manager["Manager · Port 9982"] API["REST API"] MDB[("Database")] end LB["Load\nBalancer"] W1["Worker 1"] W2["Worker N"] FS[("Shared File\nStorage")] end Manager -->|"HTTP · REST"| LB LB --> W1 LB --> W2 Manager --- FS W1 --- FS W2 --- FS style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style W1 fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style W2 fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ```yaml environment: ServiceCommunication__ServiceCommunicationType: "Rest" ServiceCommunication__ConnectionString: "http://smart-redact-worker:4885/" ``` ### RabbitMQ transport In RabbitMQ mode, the Manager sends job commands to queues. Workers consume from these queues as competing consumers. Horizontal scaling is built in: add more Workers and RabbitMQ distributes work automatically without a load balancer. ```mermaid flowchart TB subgraph SmartRedact["Manager-Worker"] subgraph Manager["Manager · Port 9982"] API["REST API"] MDB[("Database")] end Broker["RabbitMQ"] Worker["Worker · Port 4885"] FS[("Shared File Storage")] end Manager -->|"publishes"| Broker Broker -->|"consumed by"| Worker Manager --- FS Worker --- FS style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Broker fill:#fffbeb,stroke:#fde68a,color:#334155 style Worker fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ```yaml environment: ServiceCommunication__ServiceCommunicationType: "RabbitMQ" ServiceCommunication__Host: "rabbitmq" ServiceCommunication__Username: "guest" ServiceCommunication__Password: "guest" ``` **info: With REST transport, horizontal scaling requires a load balancer in front of the Workers. With RabbitMQ, Workers scale automatically through competing consumers without a load balancer.** ## Horizontal scaling: Add more Workers Each Worker instance processes multiple detections per minute (throughput depends on document size, entity density, and hardware). Add more Workers for higher throughput. RabbitMQ distributes work through competing consumers automatically. ```mermaid flowchart TB subgraph SmartRedact["Manager-Worker"] Manager["Manager"] Broker["RabbitMQ"] W1["Worker 1 + AI Model"] W2["Worker 2 + AI Model"] WN["Worker N + AI Model"] FS[("Shared File Storage")] end Manager -->|"publishes"| Broker Broker --> W1 Broker --> W2 Broker --> WN Manager --- FS W1 --- FS W2 --- FS WN --- FS style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Broker fill:#fffbeb,stroke:#fde68a,color:#334155 style W1 fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style W2 fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style WN fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ### Scale with Docker Compose Start additional Worker replicas with the `--scale` flag: ```bash docker compose up --scale smart-redact-worker=3 ``` The `deploy.replicas` field in `docker-compose.yml` only applies under Docker Swarm. With `docker compose up`, use `--scale` instead. Each Worker instance loads its own copy of the AI model and operates independently. Throughput scales linearly: three Workers produce about three times the throughput of a single Worker. ### How competing consumers work 1. All Worker instances subscribe to the same RabbitMQ queues (`worker-detection-queue`, `worker-redaction-queue`). 1. RabbitMQ distributes messages across Workers as competing consumers based on prefetch availability. 1. Each Worker processes detection jobs one at a time (configurable with `DetectionConcurrencyLimit`) and redaction jobs concurrently (default: 4). 1. If a Worker crashes mid-job, the broker redelivers the message to another available Worker. ### Horizontal scaling trade-offs | Pros | Cons | |------|------| | Linear throughput scaling | Memory: ~2.9 GB per Worker (model loaded per instance) | | Independent failure domains | Cold start time per instance (about 10 to 15 seconds for model loading) | | Straightforward to configure | Network and storage overhead | ### Configure admission control for scaled deployments Scale `MaxPendingJobs` proportionally to the number of Workers: ``` MaxPendingJobs = 2-3x * (num_workers * DetectionConcurrencyLimit) ``` For example, with 3 Workers and a detection concurrency of 1: ```yaml environment: ServiceCommunication__MaxPendingJobs: 9 # 3 * 3 * 1 ``` ## Vertical scaling: Optimize a single Worker Vertical scaling focuses on maximizing throughput within a single Worker instance using GPU acceleration and batch inference tuning. ```mermaid flowchart TB subgraph Worker["Worker"] CS["MaxChunkSize\n128–512 tokens"] BS["BatchSize\n1–100 chunks"] end style Worker fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ### How the Worker processes documents When the Worker receives a PDF, it extracts text, splits it into text chunks (sized by `MaxChunkSize`), runs entity detection on each chunk, and consolidates the results. The AI model processes one inference call at a time per Worker, which is why horizontal scaling is the primary throughput strategy. For details on `MaxChunkSize`, `BatchSize`, and other inference settings, refer to [Worker > Inference](https://www.pdf-tools.com/docs/smart-redact/references/configuration/worker#inference) and [Tune chunk size for performance](https://www.pdf-tools.com/docs/smart-redact/guides/configuration#tune-chunk-size-for-performance). ### CPU vs. GPU inference The Worker supports both CPU and GPU inference. GPU acceleration significantly reduces processing time per text chunk. | Aspect | CPU | GPU (CUDA) | |--------|-----|------------| | **Setup** | No additional requirements | Requires NVIDIA drivers and CUDA toolkit | | **Processing speed** | Baseline | Significantly faster per chunk | | **Memory** | Model loads into RAM (~2.9 GB) | Model loads into RAM + VRAM | | **Cost** | Low | Higher (GPU hardware) | | **Best for** | Dev/test, low traffic | Production, high throughput | Configure the execution provider in `appsettings.json`: ```json { "Inference": { "ExecutionProvider": "Auto", "GpuDeviceId": 0, "CpuUtilizationPercentage": 80 } } ``` | Setting | Default | Description | |---------|---------|-------------| | `ExecutionProvider` | `Auto` | Hardware for inference. `Auto` uses GPU automatically when running the `-cuda` image, and CPU otherwise. Set to `Cpu` to force CPU-only inference. | | `GpuDeviceId` | `0` | GPU device ID when using CUDA. | | `CpuUtilizationPercentage` | `80` | Percentage of CPU cores used for inference (1-100). Only applies to CPU execution. | #### Docker image variants Two Worker images are available on DockerHub: | Image | Use case | |-------|----------| | `pdftoolsag/smart-redact-worker:latest` | CPU-only inference. No GPU requirements. | | `pdftoolsag/smart-redact-worker:latest-cuda` | GPU-accelerated inference with NVIDIA CUDA. Best performance. | #### NVIDIA GPU deployment Use the GPU-specific Compose file and make sure the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) is installed on the host: ```yaml services: smart-redact-worker: deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] environment: Inference__ExecutionProvider: "Auto" Inference__GpuDeviceId: 0 ``` **info: `Auto` is the recommended default. It uses GPU automatically with the `-cuda` image, and CPU otherwise. Set to `Cpu` to force CPU-only inference.** ### Batch inference tuning The Worker splits each PDF into text chunks and groups them into **batches** before sending them to the AI model. Tuning batch size and chunk size directly controls the throughput-accuracy-memory trade-off. #### How batching works 1. The PDF is split into text chunks of up to `MaxChunkSize` tokens each. A 10-page document might produce 20-40 chunks depending on text density. 1. Chunks are grouped into batches of `BatchSize`. Each batch is sent as a single inference call to the model. 1. Fewer, larger batches mean fewer inference calls and less overhead per document. More, smaller batches use less memory. ```json { "Inference": { "BatchSize": 4, "MaxChunkSize": 256, "MaxLength": 512, "MaxWidth": 12 } } ``` #### Batch size (`BatchSize`) Controls how many text chunks the model processes in a single inference call. | BatchSize | Behavior | Memory impact | Best for | |-----------|----------|---------------|----------| | 1 (default) | One chunk per inference call | Lowest | Development, memory-constrained environments | | 2-4 | Small batches | Low-moderate | CPU deployments, balanced workloads | | 4-10 | Medium batches | Moderate | GPU deployments, production | | 10-100 | Large batches | High | GPU with ample VRAM, maximum throughput | **Example**: A 30-chunk document with `BatchSize: 1` requires 30 inference calls. With `BatchSize: 10`, it requires only 3 inference calls, significantly reducing per-document processing time. #### Chunk size (`MaxChunkSize`) Controls how many tokens (roughly words) each text chunk contains. Larger chunks give the model more context for disambiguation but take longer to process. | MaxChunkSize | Use case | Trade-off | |--------------|----------|-----------| | 384-512 | High accuracy | Maximum context per chunk, slower processing, fewer chunks per document | | 256 (default) | Balanced | Good accuracy and speed | | 128-256 | High throughput | Faster per-chunk processing, less context, more chunks per document | The model evaluates candidate entity spans within each chunk. The number of candidates scales linearly with chunk size: | MaxChunkSize | Candidates evaluated | Relative speed | |--------------|---------------------|----------------| | 512 | ~6,144 | 1x (baseline) | | 384 | ~4,608 | ~1.3x faster | | 256 | ~3,072 | ~2x faster | | 128 | ~1,536 | ~4x faster | **tip: Start with `MaxChunkSize: 256` and `BatchSize: 2`. Increase `BatchSize` first for more throughput. Only reduce `MaxChunkSize` below 256 if detection accuracy is acceptable at smaller context windows.** #### Other model parameters | Setting | Default | Description | |---------|---------|-------------| | `MaxLength` | `512` | Maximum input length the model accepts. Don't exceed without changing models. | | `MaxWidth` | `12` | Maximum entity span width in words. For example, "Bank of America Corporation" is 4 words. | ### Graph optimization The Worker applies graph optimizations at model load time to improve inference speed: ```json { "Inference": { "GraphOptimizationLevel": "All", "ExecutionMode": "Parallel" } } ``` | Setting | Default | Options | |---------|---------|---------| | `GraphOptimizationLevel` | `All` | `DisableAll`, `Basic`, `Extended`, `All` (recommended). | | `ExecutionMode` | `Parallel` | `Sequential` (single-threaded), `Parallel` (multi-threaded, recommended). | **tip: Keep `GraphOptimizationLevel` set to `All` and `ExecutionMode` set to `Parallel` for best performance. Changing these defaults is not recommended.** ## Scale Manager nodes To scale Manager nodes horizontally, switch from SQLite to **PostgreSQL** so that all Manager instances share the same state. ```mermaid flowchart LR C["Clients"] --> LB1["Load\nBalancer"] subgraph SmartRedact["Manager-Worker"] subgraph Managers["Manager Instances"] M1["Manager 1"] M2["Manager 2"] end SharedDB[("Shared\nDatabase")] subgraph Broker["RabbitMQ"] Q["Queues"] end subgraph Workers["Worker Instances"] W1["Worker 1\n+ AI Model"] W2["Worker 2\n+ AI Model"] W3["Worker N\n+ AI Model"] end SharedFS[("Shared File\nStorage")] end LB1 --> M1 LB1 --> M2 M1 --- SharedDB M2 --- SharedDB M1 --> Q M2 --> Q Q --> W1 Q --> W2 Q --> W3 Managers --- SharedFS Workers --- SharedFS style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Managers fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Broker fill:#fffbeb,stroke:#fde68a,color:#334155 style Workers fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` 1. Configure each Manager instance to use the same PostgreSQL database: ```yaml environment: Database__DatabaseType: "PostgreSql" Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-manager-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;" ``` 1. Configure a load balancer to distribute requests across Manager instances. 1. Make sure all Manager instances share the same file storage configuration. Refer to [AWS S3 file storage](https://www.pdf-tools.com/docs/smart-redact/guides/configuration#aws-s3-file-storage). **info: Each Manager instance runs its own backpressure monitor, but they all query the same PostgreSQL database. All Managers see the same pending job count regardless of which Manager created the jobs.** ## Scale Orchestrator nodes To scale the Orchestrator horizontally, switch from SQLite to **PostgreSQL** and add a shared **Redis** instance for session and token caching. Place a load balancer in front of the Orchestrator instances. ```mermaid flowchart LR subgraph Clients["Clients"] C1["Client App"] C2["HITL web app\nPort 3000"] end C2 --> LB0["Load\nBalancer"] subgraph Orchestrators["Orchestrator Instances"] O1["Orchestrator 1"] O2["Orchestrator 2"] end ODB[("Shared\nDatabase")] Redis[("Redis")] LB1["Load\nBalancer"] subgraph SmartRedact["Manager-Worker"] subgraph Managers["Manager Instances"] M1["Manager 1"] M2["Manager 2"] end SharedDB[("Shared\nDatabase")] subgraph Broker["RabbitMQ"] Q["Queues"] end subgraph Workers["Worker Instances"] W1["Worker 1\n+ AI Model"] W2["Worker 2\n+ AI Model"] W3["Worker N\n+ AI Model"] end SharedFS[("Shared File\nStorage")] end C1 --> LB1 LB0 --> O1 LB0 --> O2 O1 --- ODB O2 --- ODB O1 --- Redis O2 --- Redis O1 --> LB1 O2 --> LB1 LB1 --> M1 LB1 --> M2 M1 --- SharedDB M2 --- SharedDB M1 --> Q M2 --> Q Q --> W1 Q --> W2 Q --> W3 Managers --- SharedFS Workers --- SharedFS style Clients fill:#f0f4ff,stroke:#dbe4f0,color:#334155 style Orchestrators fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Managers fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Broker fill:#fffbeb,stroke:#fde68a,color:#334155 style Workers fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` 1. Configure each Orchestrator instance to use the same PostgreSQL database: ```yaml environment: Database__DatabaseType: "PostgreSql" Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-orchestrator-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;" ``` 1. Configure a shared Redis instance for session and token caching: ```yaml environment: Redis__ConnectionString: "shared-redis:6379" ``` 1. Place a load balancer in front of the Orchestrator instances. ## Memory planning Each Worker loads the AI model into memory at startup (~2.9 GB steady-state). Plan 4 GB per Worker to allow headroom for batch processing. ## Concurrency tuning Detection and redaction use separate RabbitMQ queues with independent concurrency limits: | Queue | Default concurrency | Reason | |-------|-------------------|--------| | `worker-detection-queue` | 1 | The AI model processes one inference at a time. Concurrent detection adds no throughput, only memory pressure. | | `worker-redaction-queue` | 4 | Lighter workload (about 100 ms per redaction), benefits from parallelism. | Override per Worker: ```yaml environment: ServiceCommunication__DetectionConcurrencyLimit: 1 ServiceCommunication__RedactionConcurrencyLimit: 4 ``` **warning: Don't increase `DetectionConcurrencyLimit` past 1. The AI model processes one inference at a time. Multiple detection threads queue up without improving throughput, only increasing memory pressure.** ## Scaling decision matrix | Scenario | Recommended strategy | |----------|---------------------| | Low traffic, cost-sensitive | Single Worker, CPU, `BatchSize: 1` | | Medium traffic, balanced | 2-3 Worker instances, CPU, `BatchSize: 2-4` | | High traffic, latency-sensitive | Multiple Workers + GPU, `BatchSize: 4-10` | | Highest traffic | Horizontal (N Workers) + GPU + batch tuning | | Burst traffic | Kubernetes HPA + multiple Workers | ### Example configurations The following examples show resource and environment fields for each scenario. The `deploy.replicas` field in these YAML blocks applies under Docker Swarm or Kubernetes; with `docker compose up`, start replicas with `--scale smart-redact-worker=N` instead. **Small deployment (dev/test):** ```yaml # 1 Worker, CPU, minimal resources smart-redact-worker: mem_limit: 4g cpus: 2.0 environment: Inference__ExecutionProvider: "Cpu" Inference__BatchSize: 1 Inference__MaxChunkSize: 256 ``` **Medium deployment (production):** ```yaml # 3 Workers, CPU, tuned batching smart-redact-worker: deploy: replicas: 3 mem_limit: 4g cpus: 2.0 environment: Inference__ExecutionProvider: "Cpu" Inference__BatchSize: 4 Inference__MaxChunkSize: 256 ServiceCommunication__DetectionConcurrencyLimit: 1 ServiceCommunication__RedactionConcurrencyLimit: 4 ``` **High-throughput deployment (production, GPU):** ```yaml # 3 Workers with GPU, aggressive batching smart-redact-worker: deploy: replicas: 3 resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] mem_limit: 6g cpus: 2.0 environment: Inference__ExecutionProvider: "Auto" Inference__GpuDeviceId: 0 Inference__BatchSize: 10 Inference__MaxChunkSize: 384 ServiceCommunication__DetectionConcurrencyLimit: 1 ServiceCommunication__RedactionConcurrencyLimit: 4 ``` --- ## Update AI Smart Redact Update AI Smart Redact by pulling new Docker images and restarting the services. Database migrations are applied automatically on startup. ## Update to a new version 1. Pull the latest Docker images: ```bash docker compose pull ``` 1. Recreate the containers with the new images: ```bash docker compose up -d ``` 1. Verify the services are running: ```bash docker compose ps ``` 1. Check the health endpoints to confirm all services are healthy: ```bash curl http://localhost:9982/healthz/ready # Manager curl http://localhost:9983/healthz/ready # Orchestrator ``` The Worker port isn't exposed to the host. To check Worker health, refer to [Health check endpoints](https://www.pdf-tools.com/docs/smart-redact/guides/monitor#health-check-endpoints). ## Database migrations Database migrations are applied automatically when each service starts. Both the Manager and Orchestrator manage their own database schemas independently. No manual migration steps are required during a version upgrade. **info: The services support both SQLite and PostgreSQL databases. Migrations are applied to whichever database backend is configured in `appsettings.json`.** ## Rollback To roll back to a previous version: 1. Stop the running services: ```bash docker compose down ``` 1. Update `docker-compose.yml` to reference the previous image tags. 1. Start the services with the previous images: ```bash docker compose up -d ``` **warning: Rolling back after a database schema migration may cause errors if the older version doesn't support the new schema. Back up your PostgreSQL databases before upgrading to a new version.** ### Back up PostgreSQL databases ```bash # Manager database docker exec smart-redact-manager-db \ pg_dump -U smartredact smartredact > manager-backup.sql # Orchestrator database docker exec smart-redact-orchestrator-db \ pg_dump -U smartredact smartredact > orchestrator-backup.sql ``` ### Restore from backup ```bash # Manager database docker exec -i smart-redact-manager-db \ psql -U smartredact smartredact < manager-backup.sql # Orchestrator database docker exec -i smart-redact-orchestrator-db \ psql -U smartredact smartredact < orchestrator-backup.sql ``` --- ## References Reference material for AI Smart Redact, grouped by topic. - **[API](https://www.pdf-tools.com/docs/smart-redact/references/api/)**: HTTP reference for the Manager API and Orchestrator API. - **[Detection](https://www.pdf-tools.com/docs/smart-redact/references/detection/)**: entity types, detection configuration, and the recognizers that produce detected entities. - **[Redaction](https://www.pdf-tools.com/docs/smart-redact/references/redaction)**: how AI Smart Redact applies an approved redaction list to a PDF. - **[Configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/)**: environment variables for the Manager, Worker, and Orchestrator services. --- ## API AI Smart Redact exposes two HTTP APIs that target different integration models. - **[Manager API](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/)** — the lower-level interface. Exposes file management, detection, and redaction as separate endpoints, leaving the surrounding workflow (queueing, status tracking, access control) to the integrator. Use the Manager API to embed AI Smart Redact directly into an existing backend. - **[Orchestrator API](https://www.pdf-tools.com/docs/smart-redact/references/api/orchestrator/)** — the higher-level interface. Each upload becomes a managed job that runs detection automatically, waits for review, runs redaction, and stores the redacted PDF for download. Authentication, request queueing, and access control are built in. Use the Orchestrator API for end-to-end workflows that benefit from these conveniences. For a component diagram showing how these APIs connect to the Worker, databases, and file storage, refer to [Architecture](https://www.pdf-tools.com/docs/smart-redact/references/architecture). --- ## Manager API The Manager API is the lower-level interface to AI Smart Redact. It exposes file management, detection, and redaction as separate endpoints, without an enclosing workflow layer. The alternative is the [Orchestrator API](https://www.pdf-tools.com/docs/smart-redact/references/api/orchestrator/jobs), which wraps these operations in a higher-level Jobs interface with built-in authentication, request queueing, and result tracking. Use the Manager API directly to integrate AI Smart Redact into an existing backend that handles these concerns itself. ## Authentication The Manager API doesn't enforce per-request authentication. It's intended to run inside a trusted environment, typically behind a reverse proxy or a private network. When integrating directly with the Manager instead of going through the Orchestrator, you're responsible for placing the service behind appropriate authentication and authorization. ## API versioning All Manager API endpoints are prefixed with `/v1`. ## Error responses When a request fails, the response body is an `ApiErrorResponse`. Per-endpoint pages list the status codes each endpoint returns; the body shape is the same in all cases. | Field | Type | Description | |-----------|-------------------------------|-------------| | `type` | `string` | URI identifier for the error type. | | `title` | `string` | Short summary of the error. | | `status` | `integer` | HTTP status code. | | `traceId` | `string` | Correlation ID for the request, useful for support and log lookup. | | `detail` | `string` | Description of the error. | | `errors` | `object` of `string` arrays | Field-level validation errors, keyed by field name. | ## Reference pages --- ## Detection The Detection endpoints run sensitive-entity detection against a previously uploaded PDF. The response contains the detected entities (text, label, page position, and confidence score) inline in the `result` object, and a reference to an FDF file produced by the job and stored on the Manager. Both are needed to start a redaction job: the entity list is passed inline as `redactionInput`, and the FDF reference is passed as `fdfFileId` and `fdfDekToken`. The FDF itself only needs to be downloaded when the entities need to be reviewed or modified visually in a PDF viewer before redaction. The cURL examples use the Manager's default address (`http://localhost:9982`); substitute the host and port of your deployment as needed. ## Sync and async processing Each detection request specifies a `processingMode`: - **`sync`** — the request blocks until detection completes. The response is `200` with the full result. - **`async`** — the request returns `202` immediately with a `jobId`. Use the result endpoint to poll until `jobStatus` is `finished` or `error`. Use sync for small, interactive flows. Use async for large documents that would exceed HTTP timeouts in sync mode, or when starting many jobs in parallel. ## Detection configuration The optional `detectionConfiguration` field on the request overrides the built-in detection defaults for that single request. Use it to add custom recognizers, change the score threshold, or supply keyword exclusions. When omitted, the built-in defaults are used. For the full schema and the available options, refer to [Detection configuration](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration). ## Endpoints ### Start a detection job `POST /v1/jobs/detection` Detects sensitive entities in a previously uploaded PDF. The behavior depends on `processingMode`: sync blocks until the result is ready; async returns immediately with a `jobId` for polling. **Request body** — [`DetectionRequest`](#detectionrequest-schema). **Response** — [`DetectionResponse`](#detectionresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `200` | Sync only. The job completed and the response contains the full result. | | `202` | Async only. The job was accepted and is running. Poll the result endpoint with the returned `jobId`. | | `400` | The request was malformed, or `pdfFileId` and `dekToken` don't match an existing file. | | `404` | No file with the given `pdfFileId` exists. | | `429` | Admission control rejected the request because too many jobs are pending. | | `503` | The job couldn't be dispatched to a worker. | **Sync example:** ```bash curl -X POST "http://localhost:9982/v1/jobs/detection" \ -H "Content-Type: application/json" \ -d "{\"processingMode\": \"sync\", \"pdfFileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}" ``` **Async example:** ```bash curl -X POST "http://localhost:9982/v1/jobs/detection" \ -H "Content-Type: application/json" \ -d "{\"processingMode\": \"async\", \"pdfFileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}" ``` ### Get the result of a detection job `GET /v1/jobs/detection/{jobId}/result` Returns the current state of an async detection job. Poll this endpoint until `jobStatus` is `finished` or `error`. The response uses the same shape whether the job is still in progress or has completed. **Path parameters:** | Name | Type | Description | |---------|-----------------|-------------| | `jobId` | `string` (UUID) | The `jobId` returned by the start-job request. | **Response** — [`DetectionResponse`](#detectionresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `200` | The job has finished. The response contains the full result. | | `202` | The job is still running. Poll again. | | `400` | The request was malformed. | | `404` | No job with the given `jobId` exists. | **Example:** ```bash curl "http://localhost:9982/v1/jobs/detection/$JOB_ID/result" ``` ## Schemas ### `DetectionRequest` schema | Field | Type | Description | |--------------------------|-----------------------------------------------------------------------|-------------| | `processingMode` | [`ProcessingMode`](#processingmode-enum) | Whether the request blocks until the job completes (`sync`) or returns immediately for polling (`async`). | | `pdfFileId` | `string` (UUID) | Identifier of the previously uploaded PDF, returned by an upload endpoint. | | `dekToken` | `string` | DEK token returned alongside the `pdfFileId` at upload time. | | `detectionConfiguration` | [`DetectionConfiguration`](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration) | Optional. Overrides the built-in detection defaults for this request. When omitted, the built-in defaults are used. | ### `DetectionResponse` schema | Field | Type | Description | |---------------|-----------------------------------------------------|-------------| | `jobId` | `string` (UUID) | Identifier of the job. Use it to poll the result endpoint. | | `jobType` | [`JobType`](#jobtype-enum) | Always `detection` for this endpoint. | | `jobStatus` | [`JobStatus`](#jobstatus-enum) | Current state of the job. | | `error` | [`ApiErrorResponse`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/#error-responses) | Set when `jobStatus` is `error`. Otherwise omitted. | | `outputFiles` | array of [`FileResult`](#fileresult-schema) | References to files produced by the job. For detection, contains one entry pointing at the FDF file with the detected entities as visual annotations. Pass `fileId` and `dekToken` as `fdfFileId` and `fdfDekToken` on a redaction request. Empty until the job is finished. | | `result` | [`DetectionResult`](#detectionresult-schema) | Detected entities returned inline. The same set is encoded in the FDF file referenced by `outputFiles`. Empty until the job is finished. | ### `DetectionResult` schema | Field | Type | Description | |--------------|---------------------------------------------------------------|-------------| | `redactions` | array of [`RedactionEntityDto`](#redactionentitydto-schema) | Detected entities. The same set is encoded in the FDF file in `outputFiles`. | ### `RedactionEntityDto` schema | Field | Type | Description | |------------------|------------------------------------------------------------|-------------| | `pageIndex` | `integer` | Zero-based page index where the entity appears. | | `text` | `string` | The matched text. Required. | | `label` | `string` | The entity type, for example `EMAIL_ADDRESS` or `PERSON`. Required. | | `score` | `number` | Confidence score between 0 and 1. | | `quadrilaterals` | array of [`QuadrilateralDto`](#quadrilateraldto-schema) | On-page bounding regions for the entity. | ### `QuadrilateralDto` schema All four corners are required. Quadrilaterals can describe rotated or skewed text regions, not only axis-aligned rectangles. | Field | Type | Description | |---------------|---------------------------------|-------------| | `bottomLeft` | [`PointDto`](#pointdto-schema) | Bottom-left corner. | | `bottomRight` | [`PointDto`](#pointdto-schema) | Bottom-right corner. | | `topRight` | [`PointDto`](#pointdto-schema) | Top-right corner. | | `topLeft` | [`PointDto`](#pointdto-schema) | Top-left corner. | ### `PointDto` schema | Field | Type | Description | |-------|----------|-------------| | `x` | `number` | X coordinate in PDF user-space points. | | `y` | `number` | Y coordinate in PDF user-space points. | ### `FileResult` schema | Field | Type | Description | |---------------------|---------------------------|-------------| | `fileId` | `string` (UUID) | Identifier of the result file. | | `fileCode` | `string` | Role of the file in the job result. | | `size` | `integer` | File size in bytes. | | `dekToken` | `string` | DEK token required to download or use the result file. | | `dekTokenExpiresAt` | `string` (UTC date-time) | Expiration of the DEK token. | ### `JobStatus` enum | Value | Description | |--------------|-------------| | `inProgress` | The job is running. | | `finished` | The job completed successfully. The result is available in `outputFiles` and `result`. | | `error` | The job failed. The cause is available in `error`. | ### `JobType` enum | Value | Description | |-------------|-------------| | `detection` | A detection job. | | `redaction` | A redaction job. | ### `ProcessingMode` enum | Value | Description | |---------|-------------| | `sync` | The request blocks until the job completes. | | `async` | The request returns immediately with a `jobId`. Poll the result endpoint until `jobStatus` is `finished` or `error`. | --- ## Files The Files endpoints handle the file lifecycle on the Manager. PDFs uploaded through these endpoints are referenced by their `fileId` in detection and redaction requests, and result files (such as the FDF produced by detection or the redacted PDF) are downloaded through the same endpoints. The cURL examples use the Manager's default address (`http://localhost:9982`); substitute the host and port of your deployment as needed. ## DEK tokens Files are encrypted at rest on the Manager. The data encryption key (DEK) for each file is wrapped in a short-lived, AES-GCM-encrypted token, the **DEK token**, which is returned alongside the `fileId` in the upload response. Every subsequent operation on that file requires the token: detection, redaction, and download. Without it, the service can't decrypt the file even though it has it. The token is returned only once and can't be retrieved later, so store it securely with the `fileId` it belongs to. The token has an expiration time, returned as `expiresAt`. After it expires, the file is no longer accessible and must be re-uploaded. The same applies if the token is lost. Result files produced by jobs (such as the FDF returned by a detection job, or the redacted PDF returned by a redaction job) are also encrypted, and each comes with its own DEK token in the job response. Most requests carry one DEK token under `dekToken`. The redaction request carries two tokens, one for the input PDF and one for the FDF, so its fields are named `pdfDekToken` and `fdfDekToken` to disambiguate. ## Endpoints ### Upload from local file `POST /v1/files/upload/fromLocal` Upload a file as a multipart form. Only `.pdf` and `.fdf` files are accepted. The response contains the `fileId` and the DEK token required for all subsequent operations on the file. **Request body** (`multipart/form-data`): | Field | Type | Description | |--------|----------|-------------| | `file` | `binary` | The file to upload. Must be `.pdf` or `.fdf`. | **Response** — [`UploadFileResponse`](#uploadfileresponse-schema). **Status codes:** | Code | Meaning | |------|---------| | `200` | The file was uploaded successfully. | | `400` | The request was malformed, the file couldn't be read, or its extension isn't `.pdf` or `.fdf`. | **Example:** ```bash curl -X POST "http://localhost:9982/v1/files/upload/fromLocal" \ -F "file=@document.pdf" ``` ### Upload from URL `POST /v1/files/upload/fromUrl` Instructs the Manager to fetch a file from a URL and store it. The Manager must have network access to the URL. Only `.pdf` and `.fdf` files are accepted. **Request body** — [`UploadFromUrlRequest`](#uploadfromurlrequest-schema). **Response** — [`UploadFileResponse`](#uploadfileresponse-schema). **Status codes:** | Code | Meaning | |------|---------| | `200` | The file was uploaded successfully. | | `400` | The URL was missing, invalid, unreachable, or the file extension isn't `.pdf` or `.fdf`. | **Example:** ```bash curl -X POST "http://localhost:9982/v1/files/upload/fromUrl" \ -H "Content-Type: application/json" \ -d '{"fileUrl": "https://example.com/document.pdf"}' ``` ### List files `GET /v1/files` Returns metadata for all files currently held by the Manager. DEK tokens aren't returned by this endpoint. **Query parameters:** | Name | Type | Description | |-------------------|-----------|-------------| | `OnlyResultFiles` | `boolean` | When `true`, only files produced as job results are returned. Defaults to `false`. | **Response** — [`GetFilesInfoResponse`](#getfilesinforesponse-schema). **Example:** ```bash curl "http://localhost:9982/v1/files?OnlyResultFiles=true" ``` ### Get file info `GET /v1/files/{fileId}` Returns metadata for a single file. DEK tokens aren't returned by this endpoint. **Path parameters:** | Name | Type | Description | |----------|-----------------|-------------| | `fileId` | `string` (UUID) | The file identifier returned by an upload. | **Response** — [`GetFileInfoResponse`](#getfileinforesponse-schema). **Example:** ```bash curl "http://localhost:9982/v1/files/$FILE_ID" ``` ### Download a file `POST /v1/files/download` Returns the raw file bytes. The DEK token is required so the Manager can decrypt the file. **Request body** — [`DownloadFileRequest`](#downloadfilerequest-schema). **Response** — the file bytes (`application/octet-stream`). **Status codes:** | Code | Meaning | |------|---------| | `200` | The file was returned successfully. | | `400` | The DEK token was missing or invalid. | | `404` | No file with the given `fileId` exists. | **Example:** ```bash curl -X POST "http://localhost:9982/v1/files/download" \ -H "Content-Type: application/json" \ -d "{\"fileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}" \ --output downloaded.pdf ``` ### Delete a file `DELETE /v1/files/{fileId}` Permanently deletes the file. After deletion, the `fileId` and DEK token can't be reused. **Path parameters:** | Name | Type | Description | |----------|-----------------|-------------| | `fileId` | `string` (UUID) | The file identifier returned by an upload. | **Response** — [`DeleteFileResponse`](#deletefileresponse-schema), containing the metadata of the deleted file. **Example:** ```bash curl -X DELETE "http://localhost:9982/v1/files/$FILE_ID" ``` ## Schemas ### `UploadFileResponse` schema | Field | Type | Description | |-------------|---------------------------|-------------| | `fileId` | `string` (UUID) | The identifier to use in subsequent operations on this file. | | `dekToken` | `string` | DEK token required for all subsequent operations. Store securely; it isn't recoverable. | | `expiresAt` | `string` (UTC date-time) | Expiration time of the DEK token. After this point, the file is no longer accessible. | ### `UploadFromUrlRequest` schema | Field | Type | Description | |-----------|----------|-------------| | `fileUrl` | `string` | URL the Manager fetches the file from. The Manager must have network access to this URL. | ### `DownloadFileRequest` schema | Field | Type | Description | |------------|-----------------|-------------| | `fileId` | `string` (UUID) | The file identifier returned by an upload. | | `dekToken` | `string` | DEK token returned alongside the `fileId` at upload time. | ### `GetFileInfoResponse` schema | Field | Type | Description | |-------------|-----------------------------------------|-------------| | `id` | `string` (UUID) | File identifier. | | `createdAt` | `string` (UTC date-time) | When the file was uploaded. | | `origin` | [`FileOrigin`](#fileorigin-enum) | How the file entered the Manager. | | `name` | `string` | Original file name, when available. | | `sizeBytes` | `integer` | File size in bytes. | | `extension` | [`FileExtension`](#fileextension-enum) | Detected file extension. | ### `GetFilesInfoResponse` schema | Field | Type | Description | |---------|---------------------------------------------------------------|-------------| | `files` | array of [`GetFileInfoResponse`](#getfileinforesponse-schema) | The files held by the Manager that match the request. | ### `DeleteFileResponse` schema Same shape as [`GetFileInfoResponse`](#getfileinforesponse-schema). Returns the metadata of the file at the moment it was deleted. ### `FileExtension` enum The Manager only accepts `.pdf` and `.fdf` uploads, so file responses return one of the following values: | Value | Description | |-----------|-------------| | `pdf` | A PDF document. | | `fdf` | An FDF file, typically a detection result that lists the entities and their on-page positions. | | `unknown` | The file was uploaded without a recognizable extension. | ### `FileOrigin` enum | Value | Description | |-------------|-------------| | `localFile` | Uploaded from a local file through `/v1/files/upload/fromLocal`. | | `url` | Fetched from a URL through `/v1/files/upload/fromUrl`. | | `jobResult` | Produced as the result of a detection or redaction job. | --- ## Redaction The Redaction endpoints redact sensitive entities from a previously uploaded PDF and return a new PDF with the entities removed. The request takes the source PDF, the FDF reference produced by a detection job, and the list of entities to redact. The response contains a reference to the redacted PDF, downloadable through the Files endpoints. The cURL examples use the Manager's default address (`http://localhost:9982`); substitute the host and port of your deployment as needed. ## Sync and async processing Each redaction request specifies a `processingMode`: - **`sync`** — the request blocks until redaction completes. The response is `200` with the full result. - **`async`** — the request returns `202` immediately with a `jobId`. Use the result endpoint to poll until `jobStatus` is `finished` or `error`. Use sync for small, interactive flows. Use async for large documents that would exceed HTTP timeouts in sync mode, or when starting many jobs in parallel. ## Endpoints ### Start a redaction job `POST /v1/jobs/redaction` Redacts the entities listed in `redactionInput` from the previously uploaded PDF and returns a new PDF with the content removed. The behavior depends on `processingMode`: sync blocks until the result is ready; async returns immediately with a `jobId` for polling. **Request body** — [`RedactionRequest`](#redactionrequest-schema). **Response** — [`RedactionResponse`](#redactionresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `200` | Sync only. The job completed and the response contains the full result. | | `202` | Async only. The job was accepted and is running. Poll the result endpoint with the returned `jobId`. | | `400` | The request was malformed, or the file references and DEK tokens don't match existing files. | | `404` | No file with the given `pdfFileId` or `fdfFileId` exists. | | `429` | Admission control rejected the request because too many jobs are pending. | | `503` | The job couldn't be dispatched to a worker. | **Sync example:** ```bash curl -X POST "http://localhost:9982/v1/jobs/redaction" \ -H "Content-Type: application/json" \ -d '{ "processingMode": "sync", "pdfFileId": "", "pdfDekToken": "", "fdfFileId": "", "fdfDekToken": "", "redactionInput": { "redactions": [ { "pageIndex": 0, "text": "John", "label": "PERSON", "score": 0.99, "quadrilaterals": [{ "bottomLeft": {"x": 235.8, "y": 671.8}, "bottomRight": {"x": 264.0, "y": 671.8}, "topRight": {"x": 264.0, "y": 682.0}, "topLeft": {"x": 235.8, "y": 682.0} }] } ] } }' ``` Replace the following: - ``: The file ID of the source PDF, returned by the upload endpoint. - ``: The DEK token for the source PDF, returned by the upload endpoint. - ``: The file ID of the FDF produced by a detection job. - ``: The DEK token for the FDF, returned in the detection job response. **Async example:** the same body, with `"processingMode": "async"`. The response returns a `jobId` to poll. ### Get the result of a redaction job `GET /v1/jobs/redaction/{jobId}/result` Returns the current state of an async redaction job. Poll this endpoint until `jobStatus` is `finished` or `error`. The response uses the same shape whether the job is still in progress or has completed. **Path parameters:** | Name | Type | Description | |---------|-----------------|-------------| | `jobId` | `string` (UUID) | The `jobId` returned by the start-job request. | **Response** — [`RedactionResponse`](#redactionresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `200` | The job has finished. The response contains the full result. | | `202` | The job is still running. Poll again. | | `400` | The request was malformed. | | `404` | No job with the given `jobId` exists. | **Example:** ```bash curl "http://localhost:9982/v1/jobs/redaction/$JOB_ID/result" ``` ## Schemas ### `RedactionRequest` schema | Field | Type | Description | |------------------|------------------------------------------------------------|-------------| | `processingMode` | [`ProcessingMode`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection#processingmode-enum) | Whether the request blocks until the job completes (`sync`) or returns immediately for polling (`async`). | | `pdfFileId` | `string` (UUID) | Identifier of the previously uploaded source PDF. | | `pdfDekToken` | `string` | DEK token returned alongside the `pdfFileId` at upload time. | | `fdfFileId` | `string` (UUID) | Identifier of the FDF file produced by a detection job, or of an FDF re-uploaded after visual editing. | | `fdfDekToken` | `string` | DEK token for the FDF file, returned alongside the `fdfFileId`. | | `redactionInput` | [`RedactionInput`](#redactioninput-schema) | The list of entities to redact. | ### `RedactionResponse` schema | Field | Type | Description | |---------------|-----------------------------------------------------------------|-------------| | `jobId` | `string` (UUID) | Identifier of the job. Use it to poll the result endpoint. | | `jobType` | [`JobType`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection#jobtype-enum) | Always `redaction` for this endpoint. | | `jobStatus` | [`JobStatus`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection#jobstatus-enum) | Current state of the job. | | `error` | [`ApiErrorResponse`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/#error-responses) | Set when `jobStatus` is `error`. Otherwise omitted. | | `outputFiles` | array of [`FileResult`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection#fileresult-schema) | References to files produced by the job. For redaction, contains one entry pointing at the redacted PDF. Empty until the job is finished. | ### `RedactionInput` schema | Field | Type | Description | |--------------|----------------------------------------------------------------------------|-------------| | `redactions` | array of [`RedactionEntityDto`](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection#redactionentitydto-schema) | Entities to redact. Same shape as `DetectionResult.redactions`. | --- ## Orchestrator API The Orchestrator API exposes the higher-level redaction workflow on top of AI Smart Redact: each upload becomes a managed job that automatically runs detection, waits for review, runs redaction, and stores the redacted PDF for download. Authentication, status tracking, request queueing, and access control are built in. For direct, low-level integration with the underlying file, detection, and redaction operations, use the [Manager API](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/) instead. ## Authentication The Jobs endpoints authenticate with an API key sent in the `X-Api-Key` header, or a Bearer JWT in the `Authorization` header. API keys are created and managed by an administrator; refer to the [Authentication guide](https://www.pdf-tools.com/docs/smart-redact/guides/authentication) for how to create one. API keys have the format `pdft_` followed by a base64url-encoded random suffix. Each key has a required expiration of up to 12 months and is shown in plain text only once at creation; if the key is lost, a new one must be created. Revocation takes effect on the next request. Requests without a valid API key or JWT receive a `401 Unauthorized` response. The per-endpoint status code tables don't repeat this. ## API versioning All Orchestrator API endpoints are prefixed with `/v1`. ## Error responses When a request fails, the response body is an `ApiErrorResponse`. Per-endpoint pages list the status codes each endpoint returns; the body shape is the same in all cases. | Field | Type | Description | |-----------|-------------------------------|-------------| | `type` | `string` | URI identifier for the error type. | | `title` | `string` | Short summary of the error. | | `status` | `integer` | HTTP status code. | | `traceId` | `string` | Correlation ID for the request, useful for support and log lookup. | | `detail` | `string` | Description of the error. | | `errors` | `object` of `string` arrays | Field-level validation errors, keyed by field name. | ## Reference pages --- ## Jobs The Jobs endpoints expose the Orchestrator-managed redaction workflow. A job is created by uploading a PDF; detection then runs automatically, the job moves to `readyForReview`, a reviewer submits the redaction list, redaction runs, and the redacted PDF is downloadable. The cURL examples use the Orchestrator's default address (`http://localhost:9983`); substitute the host and port of your deployment as needed. They also use an `$API_KEY` shell variable for the API key — refer to [Authentication](https://www.pdf-tools.com/docs/smart-redact/references/api/orchestrator/#authentication) for how to obtain one. ## Job lifecycle Each job progresses through the following statuses. Endpoints that move a job between statuses are noted alongside. | Status | Description | Set by | |-----------------------|-----------------------------------------------------------------------------|---------------------------------------| | `created` | The job has been registered. Detection hasn't started yet. | `POST /v1/jobs` | | `detectionInProgress` | Detection is running. | Automatic, after `created`. | | `readyForReview` | Detection is complete. A reviewer can now submit the redaction list. | Automatic, when detection finishes. | | `redactionInProgress` | Redaction is running. | `POST /v1/jobs/{id}/redaction` | | `finished` | Redaction is complete. The redacted PDF is available for download. | Automatic, when redaction finishes. | | `expired` | The job has expired and the redacted file is no longer available. | Automatic, when the uploaded PDF expires. | | `failed` | An error occurred while processing the job. Details are in the response. | Automatic, on failure. | ## Endpoints All endpoints require authentication. Unauthenticated requests receive `401 Unauthorized`; refer to the [Authentication](https://www.pdf-tools.com/docs/smart-redact/references/api/orchestrator/#authentication) section for details. The per-endpoint status code tables don't repeat this. ### Create a job `POST /v1/jobs` Creates a new job by uploading a PDF as multipart form data. Detection runs automatically; the response returns the job in `created` or `detectionInProgress` status. **Request body** (`multipart/form-data`): | Field | Type | Description | |--------|----------|-------------| | `file` | `binary` | The PDF to redact. | **Response** — [`JobResponse`](#jobresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `201` | The job was created. | | `400` | The request was malformed or the file couldn't be read. | **Example:** ```bash curl -X POST "http://localhost:9983/v1/jobs" \ -H "X-Api-Key: $API_KEY" \ -F "file=@document.pdf" ``` ### List jobs `GET /v1/jobs` Returns a paginated list of jobs, ordered by most recent first. Supports cursor-based pagination, status filtering, and substring search on the file name. **Query parameters:** | Name | Type | Description | |-----------------|---------------------------------------|-------------| | `pageSize` | `integer` | Items per page (1–100). Defaults to 20. | | `cursor` | `string` | Pagination cursor returned in `nextCursor` on a previous response. | | `status` | [`JobStatus`](#jobstatus-enum) | Filter by job status. | | `createdBy` | `string` | Filter by creator user ID. | | `reviewedBy` | `string` | Filter by reviewer user ID. | | `fileName` | `string` | Case-insensitive substring search on the file name. | | `sortBy` | [`JobSortField`](#jobsortfield-enum) | Sort field. Defaults to `createdAt`. | | `sortDirection` | [`SortDirection`](#sortdirection-enum) | Sort direction. Defaults to `desc`. | **Response** — [`JobSummaryResponsePaginatedResponse`](#jobsummaryresponsepaginatedresponse-schema). **Example:** ```bash curl "http://localhost:9983/v1/jobs?status=readyForReview&pageSize=50" \ -H "X-Api-Key: $API_KEY" ``` ### Get a job `GET /v1/jobs/{id}` Returns the full details of a job, including the detection result when available. **Path parameters:** | Name | Type | Description | |------|-----------------|-------------| | `id` | `string` (UUID) | The job ID. | **Response** — [`JobResponse`](#jobresponse-schema). **Status codes:** | Code | Meaning | |-------|---------| | `200` | The job was found. | | `404` | No job with the given `id` exists. | **Example:** ```bash curl "http://localhost:9983/v1/jobs/$JOB_ID" \ -H "X-Api-Key: $API_KEY" ``` ### Start redaction for a job `POST /v1/jobs/{id}/redaction` Submits the reviewed list of entities to redact and starts the redaction step. The job must be in `readyForReview`. **Path parameters:** | Name | Type | Description | |------|-----------------|-------------| | `id` | `string` (UUID) | The job ID. | **Request body** — [`RedactionInput`](#redactioninput-schema). **Response** — [`JobResponse`](#jobresponse-schema), with `status` updated to `redactionInProgress`. **Status codes:** | Code | Meaning | |-------|---------| | `200` | Redaction was started. | | `404` | No job with the given `id` exists. | | `409` | The job isn't in `readyForReview`. | **Example:** ```bash curl -X POST "http://localhost:9983/v1/jobs/$JOB_ID/redaction" \ -H "X-Api-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "redactions": [ { "pageIndex": 0, "text": "John", "label": "PERSON", "score": 0.99, "quadrilaterals": [{ "bottomLeft": {"x": 235.8, "y": 671.8}, "bottomRight": {"x": 264.0, "y": 671.8}, "topRight": {"x": 264.0, "y": 682.0}, "topLeft": {"x": 235.8, "y": 682.0} }] } ] }' ``` ### Download a job file `GET /v1/jobs/{id}/files/{fileType}` Downloads one of the files associated with a job: the original PDF, the FDF detection annotations, or the redacted output PDF. **Path parameters:** | Name | Type | Description | |------------|-------------------------------------|-------------| | `id` | `string` (UUID) | The job ID. | | `fileType` | [`JobFileType`](#jobfiletype-enum) | Which file to download. | **Response** — the file bytes (`application/pdf` or `application/fdf`). **Status codes:** | Code | Meaning | |-------|---------| | `200` | The file was returned. | | `404` | The job or the requested file type doesn't exist. | | `502` | The Orchestrator couldn't fetch the file from the Manager. | **Example:** ```bash curl "http://localhost:9983/v1/jobs/$JOB_ID/files/redactedPdf" \ -H "X-Api-Key: $API_KEY" \ --output redacted.pdf ``` ## Schemas ### `JobResponse` schema | Field | Type | Description | |-------------------|---------------------------------------------------|-------------| | `id` | `string` (UUID) | Job identifier. | | `fileName` | `string` | Original file name of the uploaded PDF. | | `status` | [`JobStatus`](#jobstatus-enum) | Current job status. | | `createdBy` | [`UserInfoResponse`](#userinforesponse-schema) | The user that created the job. | | `reviewedBy` | [`UserInfoResponse`](#userinforesponse-schema) | The user that submitted the redaction list. Set after redaction starts. | | `createdAt` | `string` (UTC date-time) | When the job was created. | | `updatedAt` | `string` (UTC date-time) | When the job was last updated. | | `pdfExpiresAt` | `string` (UTC date-time) | When the uploaded PDF expires. After this point, the job moves to `expired`. | | `fdfExpiresAt` | `string` (UTC date-time) | When the detection result (FDF) expires. Set once detection completes. | | `redactedPdfExpiresAt` | `string` (UTC date-time) | When the redacted PDF expires. Set once redaction completes. | | `detectionResult` | [`DetectionResult`](#detectionresult-schema) | Detected entities. Available once the job reaches `readyForReview`. | ### `JobSummaryResponse` schema | Field | Type | Description | |--------------|---------------------------------------------------|-------------| | `id` | `string` (UUID) | Job identifier. | | `fileName` | `string` | Original file name of the uploaded PDF. | | `status` | [`JobStatus`](#jobstatus-enum) | Current job status. | | `createdBy` | [`UserInfoResponse`](#userinforesponse-schema) | The user that created the job. | | `reviewedBy` | [`UserInfoResponse`](#userinforesponse-schema) | The user that submitted the redaction list. | | `createdAt` | `string` (UTC date-time) | When the job was created. | | `updatedAt` | `string` (UTC date-time) | When the job was last updated. | | `pdfExpiresAt` | `string` (UTC date-time) | When the uploaded PDF expires. After this point, the job moves to `expired`. | | `fdfExpiresAt` | `string` (UTC date-time) | When the detection result (FDF) expires. Set once detection completes. | | `redactedPdfExpiresAt` | `string` (UTC date-time) | When the redacted PDF expires. Set once redaction completes. | ### `JobSummaryResponsePaginatedResponse` schema | Field | Type | Description | |---------------|-----------------------------------------------------------------|-------------| | `items` | array of [`JobSummaryResponse`](#jobsummaryresponse-schema) | Page of jobs. | | `pageSize` | `integer` | Page size that was applied. | | `totalCount` | `integer` | Total number of jobs matching the query. | | `nextCursor` | `string` | Cursor to pass on the next call. Absent when there are no more pages. | | `hasNextPage` | `boolean` | Whether more pages are available. | ### `RedactionInput` schema | Field | Type | Description | |--------------|---------------------------------------------------------------|-------------| | `redactions` | array of [`RedactionEntityDto`](#redactionentitydto-schema) | Entities to redact. | ### `RedactionEntityDto` schema | Field | Type | Description | |------------------|------------------------------------------------------------|-------------| | `pageIndex` | `integer` | Zero-based page index where the entity appears. | | `text` | `string` | The matched text. Required. | | `label` | `string` | The entity type, for example `EMAIL_ADDRESS` or `PERSON`. Required. | | `score` | `number` | Confidence score between 0 and 1. | | `quadrilaterals` | array of [`QuadrilateralDto`](#quadrilateraldto-schema) | On-page bounding regions for the entity. | ### `QuadrilateralDto` schema All four corners are required. Quadrilaterals can describe rotated or skewed text regions, not only axis-aligned rectangles. | Field | Type | Description | |---------------|---------------------------------|-------------| | `bottomLeft` | [`PointDto`](#pointdto-schema) | Bottom-left corner. | | `bottomRight` | [`PointDto`](#pointdto-schema) | Bottom-right corner. | | `topRight` | [`PointDto`](#pointdto-schema) | Top-right corner. | | `topLeft` | [`PointDto`](#pointdto-schema) | Top-left corner. | ### `PointDto` schema | Field | Type | Description | |-------|----------|-------------| | `x` | `number` | X coordinate in PDF user-space points. | | `y` | `number` | Y coordinate in PDF user-space points. | ### `DetectionResult` schema | Field | Type | Description | |--------------|---------------------------------------------------------------|-------------| | `redactions` | array of [`RedactionEntityDto`](#redactionentitydto-schema) | Detected entities returned by the detection step. | ### `UserInfoResponse` schema | Field | Type | Description | |------------|-----------|-------------| | `userId` | `string` | User identifier. | | `email` | `string` | User's email address. | | `fullName` | `string` | User's full name. | | `isActive` | `boolean` | Whether the user account is active. | ### `JobStatus` enum | Value | Description | |-----------------------|-------------| | `created` | The job is registered. Detection hasn't started yet. | | `detectionInProgress` | Detection is running. | | `readyForReview` | Detection is complete. The redaction list is ready for review. | | `redactionInProgress` | Redaction is running. | | `finished` | Redaction is complete. | | `expired` | The job has expired. | | `failed` | The job failed. | ### `JobFileType` enum | Value | Description | |---------------|-------------| | `pdf` | The original uploaded PDF. | | `fdf` | The FDF file produced by detection. | | `redactedPdf` | The redacted PDF, available once the job is `finished`. | ### `JobSortField` enum | Value | Description | |-------------|-------------| | `createdAt` | Sort by creation time. | | `updatedAt` | Sort by last update time. | ### `SortDirection` enum | Value | Description | |--------|-------------| | `asc` | Ascending. | | `desc` | Descending. | --- ## Architecture AI Smart Redact is composed of three subsystems. The **Manager** stores files and runs detection or redaction jobs. The **Orchestrator** sits in front of the Manager to add authentication, user management, and the review workflow that powers the Human-in-the-Loop (HITL) web application. The **Worker** runs the detection pipeline and the AI model, and is internal to the Docker network. ## Component diagram In the default configuration, the Manager and Worker communicate through a REST API over HTTP. Each stateful subsystem has its own PostgreSQL database, and the Manager and Worker share a single file storage volume. The Manager and the Worker both read and write files directly to the shared storage. The Manager doesn't proxy file I/O for the Worker. The Orchestrator additionally uses a Redis instance for DEK-token caching, which is shipped with the default Docker Compose stack but isn't shown in the diagram below for clarity. ```mermaid flowchart TB subgraph Clients["Clients"] C1["Client App"] C2["HITL web app\nPort 3000"] end subgraph Orchestrator["Orchestrator · Port 9983"] OAPI["REST API + JWT Auth"] ODB[("Database")] end subgraph SmartRedact["Manager-Worker"] subgraph Manager["Manager · Port 9982"] MAPI["REST API"] MDB[("Database")] end Worker["Worker · Port 4885 (internal)"] FS[("File Storage")] end C1 --> Manager C2 --> Orchestrator Orchestrator -->|"HTTP/REST"| Manager OAPI --- ODB MAPI --- MDB Manager -->|"HTTP/REST"| Worker Manager --- FS Worker --- FS style Clients fill:#f0f4ff,stroke:#dbe4f0,color:#334155 style Orchestrator fill:#ecfdf5,stroke:#bbf7d0,color:#334155 style SmartRedact fill:#fafafa,stroke:#d1d5db,color:#334155 style Manager fill:#eff6ff,stroke:#bfdbfe,color:#334155 style Worker fill:#ecfdf5,stroke:#bbf7d0,color:#334155 ``` ## Subsystems | Subsystem | Purpose | Default port | |---|---|---| | **Manager** | File storage, detection and redaction jobs, persistence | 9982 | | **Orchestrator** | Authentication, user management, HITL workflow | 9983 | | **Worker** | Detection pipeline, AI model inference | 4885 (internal) | ### Manager The Manager owns file storage and the job lifecycle. Clients call the Manager directly for API integrations, or through the Orchestrator for browser-based workflows. The Manager persists job state in PostgreSQL and reads or writes PDFs and intermediate artifacts to the shared file storage volume. ### Orchestrator The Orchestrator wraps the Manager with JWT authentication, user accounts, and the review workflow that powers the HITL web application. It has its own PostgreSQL database for users, sessions, and HITL state. The HITL web application talks to the Orchestrator only. The Orchestrator also uses a **Redis** instance as an optional cache for DEK tokens. Redis is included in the default Docker Compose stack but isn't strictly required: if no Redis connection string is configured, the Orchestrator falls back to caching DEK tokens in memory. ### Worker The Worker accepts detection or redaction commands from the Manager (HTTP/REST in the default transport), reads the PDF directly from shared file storage, runs the detection pipeline (pattern matching, keyword matching, and AI model inference), and writes results back to file storage. The Worker port (4885) isn't exposed outside the Docker network. File access goes straight to the configured backend, which is either a shared local volume mounted on both Manager and Worker or an S3-compatible object store. The Worker doesn't fetch or upload files through the Manager's REST API. ## Protocols | Protocol | Where it's used | |---|---| | **HTTP** | Clients to Manager or Orchestrator | | **HTTP/REST** | Orchestrator to Manager, Manager to Worker (default transport) | | **SQL** | Manager and Orchestrator to their PostgreSQL databases (over the Npgsql client) | | **file I/O** | Manager and Worker each access shared storage directly (local volume or S3-compatible object store) | | **inference** | Detection Pipeline to AI model | ## Deployment variants The component diagram shows the default REST transport. For higher throughput, AI Smart Redact also supports a RabbitMQ-based variant with multiple Workers behind shared queues, multiple Manager instances behind a load balancer, and external file storage on S3. Refer to [Scale AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/scale) for these variants and tuning guidance. ## Next steps - [Get started](https://www.pdf-tools.com/docs/smart-redact/getting-started/) with a Docker Compose deployment. - [Configure AI Smart Redact](https://www.pdf-tools.com/docs/smart-redact/guides/configuration) for production settings. - [API reference](https://www.pdf-tools.com/docs/smart-redact/references/api/) for endpoint documentation across the three subsystems. --- ## Configuration reference AI Smart Redact is deployed as three services: **Manager**, **Worker**, and **Orchestrator**, plus an optional **Human-in-the-Loop (HITL) web application** that provides a browser-based interface to the Orchestrator. For roles, default ports, and how the components interact, refer to [Architecture](https://www.pdf-tools.com/docs/smart-redact/references/architecture). For HITL web application configuration, refer to [HITL web application](https://www.pdf-tools.com/docs/smart-redact/guides/hitl-web-application). The Manager and Worker share `FileStorage` and `Encryption` configuration; the values must match for files to flow between them. The Orchestrator runs against the Manager API and has no shared sections. ## Environment variables AI Smart Redact services run as Docker containers. Configure each service by setting environment variables on the container, typically in `docker-compose.yml` or the equivalent of your runtime. Settings are organized into sections such as `Encryption` or `WebServer`. The environment-variable name is the section name, two underscores, then the field name. For example, the `EncryptionKey` field in the `Encryption` section becomes: ```bash Encryption__EncryptionKey= ``` The per-service pages list every available section and field. ## Reference pages --- ## Manager The Manager is the core service of AI Smart Redact. It exposes the [Manager API](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/), persists job state in a database, encrypts files at rest, and dispatches detection and redaction work to the Worker. Set environment variables on the Manager container to configure it; the default port is `9982`. For the naming convention and shared notes, refer to [Configuration reference](https://www.pdf-tools.com/docs/smart-redact/references/configuration/). ## Default `appsettings.json` ```json { "Database": { "DatabaseType": "SqlLite" }, "FileStorage": { "FileStorageType": "HostFileSystem", "FilesDirectoryPath": "/app/storage_folder" }, "Encryption": { "EncryptionKey": "", "DekTokenTtlMinutes": 1440 }, "ServiceCommunication": { "ServiceCommunicationType": "Rest", "ConnectionString": "http://localhost:4885/" }, "JobOptions": { "TimeoutMinutes": 60 }, "Licensing": { "LicenseKey": "", "LgsURL": "" }, "WebServer": { "PortNumber": 9982, "MaxFileSizeBytes": 104857600, "MaxConcurrentConnections": 1000, "RequestHeadersTimeout": null, "KeepAliveTimeout": null, "MinRequestBodyDataRateBytesPerSecond": null, "MinRequestBodyDataRateGracePeriod": null }, "LogFilePath": "./logs/smart-redact-manager-log.txt", "LogRetentionDays": 7 } ``` Each section is described below. ## Licensing AI Smart Redact requires a valid license key. The Manager performs soft validation: it starts even with a missing or invalid key, but rejects API requests with `403 Forbidden` until a valid key is configured. ```bash Licensing__LicenseKey= ``` | Setting | Default | Description | |---------|---------|-------------| | `LicenseKey` | required | The AI Smart Redact license key issued by Pdftools. | | `LgsURL` | — | Optional URL of an on-premise [License Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/) for air-gapped deployments. | ## Database The Manager stores job and file metadata in a relational database. The `Database` section selects the engine and provides a connection string. ```bash Database__DatabaseType=PostgreSql Database__ConnectionString=Host=...;Database=...;Username=...;Password=... ``` | Setting | Default | Description | |---------|---------|-------------| | `DatabaseType` | required | One of `PostgreSql`, `SqlLite`. | | `ConnectionString` | required (except `SqlLite`) | Provider-specific connection string. | ## File storage PDFs uploaded through the Manager API and the FDF and redacted-PDF outputs produced by jobs are persisted to a file store. The Worker reads from and writes to the same store, so the Manager and Worker must share the `FileStorage` configuration. ```bash FileStorage__FileStorageType=AwsS3 FileStorage__ConnectionString=; ``` | Setting | Default | Description | |---------|---------|-------------| | `FileStorageType` | required | One of `HostFileSystem`, `AwsS3`, `MinIO`. | | `ConnectionString` | required for `AwsS3`, `MinIO` | Backend-specific connection string. Format depends on `FileStorageType`. | | `FilesDirectoryPath` | required for `HostFileSystem` | Filesystem path used when `FileStorageType` is `HostFileSystem`. | ### Connection string formats - **`AwsS3`**: `;` (or the full form `aws.s3://bucket=;region=`). - **`MinIO`**: `minio.s3://keyId=;key=;bucket=;serviceUrl=` (or `aws.s3://keyId=;key=;bucket=;serviceUrl=`). The MinIO secret key parameter is named `key=`, matching the underlying S3 client. - **`HostFileSystem`**: not used; configure `FilesDirectoryPath` instead. ## Encryption Files at rest are encrypted with AES-256-GCM. The Manager wraps each file's data encryption key (DEK) in a short-lived, AES-GCM-encrypted token, the DEK token, returned to the client at upload time; subsequent operations on the file require the token. The Worker uses the same `Encryption` configuration as the Manager: both services must agree on the key. ```bash Encryption__EncryptionKey= Encryption__DekTokenTtlMinutes=1440 ``` | Setting | Default | Description | |---------|---------|-------------| | `EncryptionKey` | required | Base64-encoded 32-byte key encryption key (KEK). Generate with `openssl rand -base64 32`. | | `DekTokenTtlMinutes` | `1440` | DEK token lifetime in minutes (default: 24 hours). Files and jobs are retained for at least `ceil(DekTokenTtlMinutes / 1440)` days; sub-day TTLs still round up to one day. A daily cleanup then deletes expired entries, so files can outlive the TTL by up to another 24 hours. | ## Service communication The Manager dispatches detection and redaction jobs to the Worker. The transport, broker location, concurrency limits, and resilience policies live under `ServiceCommunication`. ### Transport Selects how the Manager sends jobs to the Worker. With `Rest`, the Manager calls the Worker directly over HTTP, suitable for single-Worker deployments. With `RabbitMQ`, the Manager publishes jobs to a queue and Workers consume them; this lets multiple Worker instances share the load. ```bash ServiceCommunication__ServiceCommunicationType=RabbitMQ ServiceCommunication__Host= ServiceCommunication__Username= ServiceCommunication__Password= ``` For REST transport, the connection string points to the Worker URL: ```bash ServiceCommunication__ServiceCommunicationType=Rest ServiceCommunication__ConnectionString=http://:4885/ ``` | Setting | Default | Description | |---------|---------|-------------| | `ServiceCommunicationType` | required | `Rest` or `RabbitMQ`. The Worker must use the same value. | | `ConnectionString` | required for `Rest` | Base URL of the Worker. | | `Host` | required for `RabbitMQ` | RabbitMQ host name. | | `Username` | required for `RabbitMQ` | RabbitMQ username. | | `Password` | required for `RabbitMQ` | RabbitMQ password. | | `RetryCount` | `3` | Retries on transport-level failures (Manager → Worker) before the message is moved to the error queue. Distinct from the Orchestrator's `MaxDetectionRetries`, which retries at the Orchestrator → Manager layer. | ### REST concurrency Caps on how many concurrent REST calls the Manager sends to the Worker. Applies only when `ServiceCommunicationType` is `Rest`; with RabbitMQ, the broker handles dispatch and the per-Worker concurrency is configured on the Worker. The Worker-side limits live on the [Worker configuration page](https://www.pdf-tools.com/docs/smart-redact/references/configuration/worker#concurrency). ```bash ServiceCommunication__RestSemaphoreLimit=10 ``` | Setting | Default | Description | |---------|---------|-------------| | `RestSemaphoreLimit` | `10` | Maximum concurrent REST calls from the Manager to the Worker. | ### Admission control A safeguard against unbounded queue buildup. When the in-progress job count reaches the configured limit, the Manager rejects new requests with `429 Too Many Requests` instead of letting work pile up. Without it, a sustained burst of requests can grow the queue indefinitely and degrade end-to-end latency without any visible signal to clients. Admission control is disabled by default. Set `MaxPendingJobs` to enable it. Optionally set `HealthCheckPendingJobThreshold` so the readiness probe reports `Degraded` before the hard limit is reached. The values below are an illustrative starting point: ```bash ServiceCommunication__MaxPendingJobs=20 ServiceCommunication__HealthCheckPendingJobThreshold=15 ``` | Setting | Default | Description | |---------|---------|-------------| | `MaxPendingJobs` | `null` (disabled) | Maximum in-progress jobs across all types. New requests are rejected with `429` once the limit is reached. | | `HealthCheckPendingJobThreshold` | `null` (disabled) | Pending-job count at or above which `/healthz/ready` reports `Degraded`. | | `BackpressureMonitorIntervalSeconds` | `5` | How often the cached pending-job count is refreshed from the database. | ## Job options ```bash JobOptions__TimeoutMinutes=60 ``` | Setting | Default | Description | |---------|---------|-------------| | `TimeoutMinutes` | `60` | Maximum total lifetime of a job, including queue time and Worker processing. Range 1 to 1440 minutes (24 hours). Jobs that exceed the deadline are marked as failed. | ## Web server The `WebServer` section configures the Kestrel HTTP server. ```bash WebServer__PortNumber=9982 WebServer__MaxFileSizeBytes=104857600 WebServer__MaxConcurrentConnections=1000 ``` | Setting | Default | Description | |---------|---------|-------------| | `PortNumber` | `9982` | TCP port the Manager listens on. | | `MaxFileSizeBytes` | `104857600` (100 MB) | Maximum allowed multipart upload size. Oversized uploads return `413`. Set to `null`, `0`, or a negative value to remove the limit. | | `MaxConcurrentConnections` | `1000` | Maximum concurrent connections accepted by Kestrel. Excess connections are rejected at the TCP level. Set to `null`, `0`, or a negative value to remove the limit. | | `RequestHeadersTimeout` | `null` (Kestrel default) | Maximum time spent waiting for request headers. Format: `hh:mm:ss`. | | `KeepAliveTimeout` | `null` (Kestrel default) | Idle-connection lifetime. Format: `hh:mm:ss`. | | `MinRequestBodyDataRateBytesPerSecond` | `null` (Kestrel default) | Minimum upload rate before Kestrel disconnects a slow client. Set to `0` to disable the check. | | `MinRequestBodyDataRateGracePeriod` | `null` (Kestrel default) | Grace period before the minimum upload rate is enforced. Format: `hh:mm:ss`. | If both the Manager and the Orchestrator are deployed, configure the same `MaxFileSizeBytes` value on both. Otherwise the Orchestrator can accept files that the Manager later rejects. ## Logging Application logs are written to the console and, optionally, to a file. The fields are top-level (no section prefix). ```bash LogFilePath=./logs/smart-redact-manager-log.txt LogRetentionDays=7 ``` | Setting | Default | Description | |---------|---------|-------------| | `LogFilePath` | — | Path of the rolling-daily log file inside the container. Leave empty to disable file logging. | | `LogRetentionDays` | `7` | Number of days log files are retained on disk. | The minimum log level isn't a separate setting. It's derived from the standard `ASPNETCORE_ENVIRONMENT` environment variable: when set to `Development`, the service emits `Debug`-level logs in a developer-friendly console format; any other value (the default) emits `Information`-level logs in JSON. Use `Development` only for local diagnostics. --- ## Orchestrator The Orchestrator is the higher-level service in front of the Manager. It exposes the [Orchestrator API](https://www.pdf-tools.com/docs/smart-redact/references/api/orchestrator/), authenticates clients with API keys and JWT bearer tokens, persists job records in its own database, and caches DEK tokens in Redis so files held by the Manager remain accessible across requests. Set environment variables on the Orchestrator container to configure it; the default port is `9983`. For the naming convention and shared notes, refer to [Configuration reference](https://www.pdf-tools.com/docs/smart-redact/references/configuration/). ## Default `appsettings.json` ```json { "Database": { "DatabaseType": "SqlLite", "ConnectionString": "" }, "Jwt": { "SecretKey": "", "ExpirationMinutes": 15, "RefreshTokenExpirationDays": 30 }, "Licensing": { "LicenseKey": "", "LgsURL": "" }, "WebServer": { "PortNumber": 9983, "MaxFileSizeBytes": 104857600, "MaxConcurrentConnections": 1000, "RequestHeadersTimeout": null, "KeepAliveTimeout": null, "MinRequestBodyDataRateBytesPerSecond": null, "MinRequestBodyDataRateGracePeriod": null }, "ManagerApi": { "BaseUrl": "http://localhost:9982/", "PollingIntervalSeconds": 10, "MaxDetectionRetries": 2 }, "Redis": { "ConnectionString": "" }, "AuditEvents": { "RetentionDays": 365 }, "LogFilePath": "./logs/smart-redact-orchestrator-log.txt", "LogRetentionDays": 7 } ``` Each section is described below. ## Licensing The Orchestrator requires a license key. ```bash Licensing__LicenseKey= ``` | Setting | Default | Description | |---------|---------|-------------| | `LicenseKey` | required | The AI Smart Redact license key issued by Pdftools. | | `LgsURL` | — | Optional URL of an on-premise [License Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/) for air-gapped deployments. | ## Database The Orchestrator stores user accounts, API keys, audit events, and job records in its own database, separate from the Manager's. ```bash Database__DatabaseType=PostgreSql Database__ConnectionString=Host=...;Database=...;Username=...;Password=... ``` | Setting | Default | Description | |---------|---------|-------------| | `DatabaseType` | required | One of `PostgreSql`, `SqlLite`. | | `ConnectionString` | required (except `SqlLite`) | Provider-specific connection string. | ## Manager API The Orchestrator forwards file, detection, and redaction operations to the Manager. The `ManagerApi` section configures the connection. ```bash ManagerApi__BaseUrl=http://:9982/ ``` | Setting | Default | Description | |---------|---------|-------------| | `BaseUrl` | required | Base URL of the Manager, including scheme and port. | | `PollingIntervalSeconds` | `10` | Interval at which the Orchestrator polls the Manager for asynchronous detection results. | | `MaxDetectionRetries` | `2` | Maximum detection retries the Orchestrator sends to the Manager before marking a job as failed. Distinct from the Manager's `RetryCount`, which retries at the Manager → Worker transport layer. | ## JWT The Orchestrator issues JWT bearer tokens for the human-facing parts of the API. API keys are validated separately and don't depend on this section. ```bash Jwt__SecretKey= Jwt__ExpirationMinutes=15 Jwt__RefreshTokenExpirationDays=30 ``` | Setting | Default | Description | |---------|---------|-------------| | `SecretKey` | required | HMAC-SHA256 signing key, minimum 32 characters. Generate with `openssl rand -base64 64`. | | `ExpirationMinutes` | `15` | Access-token lifetime in minutes. | | `RefreshTokenExpirationDays` | `30` | Refresh-token lifetime in days. | ## Redis The Orchestrator caches DEK tokens received from the Manager in Redis so that subsequent operations (detection, redaction, file download) can reuse them across instances. Deploy Redis without persistence (no AOF, no RDB) so that on restart all cached tokens are lost and the corresponding files become cryptographically inaccessible. This supports crypto-erasure. ```bash Redis__ConnectionString=: ``` | Setting | Default | Description | |---------|---------|-------------| | `ConnectionString` | empty | Connection string of the Redis instance. When empty, the Orchestrator uses an in-memory fallback that doesn't survive a restart and can't be shared between instances. | ## Audit events The Orchestrator records audit events. Records older than the retention window are deleted automatically. ```bash AuditEvents__RetentionDays=365 ``` | Setting | Default | Description | |---------|---------|-------------| | `RetentionDays` | `365` | Number of days audit events are retained. Must be a positive integer. | ## Web server ```bash WebServer__PortNumber=9983 WebServer__MaxFileSizeBytes=104857600 WebServer__MaxConcurrentConnections=1000 ``` | Setting | Default | Description | |---------|---------|-------------| | `PortNumber` | `9983` | TCP port the Orchestrator listens on. | | `MaxFileSizeBytes` | `104857600` (100 MB) | Maximum allowed multipart upload size. Set to `null`, `0`, or a negative value to remove the limit. | | `MaxConcurrentConnections` | `1000` | Maximum concurrent connections accepted by Kestrel. | The remaining Kestrel limits (`RequestHeadersTimeout`, `KeepAliveTimeout`, `MinRequestBodyDataRateBytesPerSecond`, `MinRequestBodyDataRateGracePeriod`) accept the same values as on the Manager. Refer to [Web server](https://www.pdf-tools.com/docs/smart-redact/references/configuration/manager#web-server) on the Manager configuration page. The Orchestrator forwards uploads to the Manager. Configure the same `MaxFileSizeBytes` on both services, otherwise the Orchestrator can accept files that the Manager later rejects. ## Logging Application logs are written to the console and, optionally, to a file. The fields are top-level (no section prefix). ```bash LogFilePath=./logs/smart-redact-orchestrator-log.txt LogRetentionDays=7 ``` | Setting | Default | Description | |---------|---------|-------------| | `LogFilePath` | — | Path of the rolling-daily log file inside the container. Leave empty to disable file logging. | | `LogRetentionDays` | `7` | Number of days log files are retained on disk. | The minimum log level isn't a separate setting. It's derived from the standard `ASPNETCORE_ENVIRONMENT` environment variable: when set to `Development`, the service emits `Debug`-level logs in a developer-friendly console format; any other value (the default) emits `Information`-level logs in JSON. Use `Development` only for local diagnostics. --- ## Worker The Worker performs detection and redaction. Only the Manager calls it; there is no externally exposed API. Set environment variables on the Worker container to configure it; the default port is `4885`. The configuration applies per Worker instance, so run multiple Workers to scale throughput. For the naming convention and shared notes, refer to [Configuration reference](https://www.pdf-tools.com/docs/smart-redact/references/configuration/). The Worker shares two configuration sections with the Manager: `FileStorage` and `Encryption`. Both services must hold the same values. ## Default `appsettings.json` ```json { "WebServer": { "PortNumber": 4885, "MaxFileSizeBytes": null, "MaxConcurrentConnections": 1000, "RequestHeadersTimeout": null, "KeepAliveTimeout": null, "MinRequestBodyDataRateBytesPerSecond": null, "MinRequestBodyDataRateGracePeriod": null }, "LogFilePath": "./logs/smart-redact-worker-log.txt", "LogRetentionDays": 7, "FileStorage": { "FileStorageType": "HostFileSystem", "FilesDirectoryPath": "/app/storage_folder" }, "Encryption": { "EncryptionKey": "", "DekTokenTtlMinutes": 1440 }, "ServiceCommunication": { "ServiceCommunicationType": "Rest" }, "Inference": { "ExecutionProvider": "Auto", "GpuDeviceId": 0, "CpuUtilizationPercentage": 80, "GraphOptimizationLevel": "All", "ExecutionMode": "Parallel", "MaxChunkSize": 256, "MaxLength": 512, "MaxWidth": 12, "BatchSize": 1 }, "Licensing": { "LicenseKey": "", "LgsURL": "" } } ``` Each section is described below. ## Licensing The Worker validates the license at startup and exits if the key is missing or invalid. ```bash Licensing__LicenseKey= ``` | Setting | Default | Description | |---------|---------|-------------| | `LicenseKey` | required | The AI Smart Redact license key issued by Pdftools. Must match the Manager. | | `LgsURL` | — | Optional URL of an on-premise [License Gateway Service](https://www.pdf-tools.com/docs/licenses/configure/) for air-gapped deployments. | ## File storage The Worker reads input files from and writes output files to the same store as the Manager. The fields and accepted values are the same. Refer to [File storage](https://www.pdf-tools.com/docs/smart-redact/references/configuration/manager#file-storage) on the Manager configuration page. ## Encryption The Worker uses the same encryption key as the Manager to unwrap DEK tokens received with each job. The fields and accepted values are the same. Refer to [Encryption](https://www.pdf-tools.com/docs/smart-redact/references/configuration/manager#encryption) on the Manager configuration page. ## Service communication The transport configured here must match the Manager's. ### Transport For RabbitMQ, the Worker connects to the same broker as the Manager. ```bash ServiceCommunication__ServiceCommunicationType=RabbitMQ ServiceCommunication__Host= ServiceCommunication__Username= ServiceCommunication__Password= ``` For REST transport, only the type is set on the Worker; the Manager initiates all calls to the Worker's HTTP endpoints on the configured `WebServer` port. ```bash ServiceCommunication__ServiceCommunicationType=Rest ``` | Setting | Default | Description | |---------|---------|-------------| | `ServiceCommunicationType` | required | `Rest` or `RabbitMQ`. Must match the Manager. | | `Host` | required for `RabbitMQ` | Broker host name. | | `Username` | required for `RabbitMQ` | Broker username. | | `Password` | required for `RabbitMQ` | Broker password. | ### Concurrency Caps on how many jobs each Worker instance processes in parallel. Detection holds an inference slot for the duration of the job, so running multiple detections in parallel adds memory pressure without improving throughput; the default is 1. Redaction is lighter and runs up to four jobs in parallel by default. ```bash ServiceCommunication__DetectionConcurrencyLimit=1 ServiceCommunication__RedactionConcurrencyLimit=4 ``` | Setting | Default | Description | |---------|---------|-------------| | `DetectionConcurrencyLimit` | `1` | Maximum detection jobs processed concurrently by this Worker instance. | | `RedactionConcurrencyLimit` | `4` | Maximum redaction jobs processed concurrently by this Worker instance. | ## Inference The Worker runs a semantic detection model for context-aware entity recognition. The `Inference` section tunes the inference runtime and the chunking behavior. ```bash Inference__ExecutionProvider=Auto Inference__GpuDeviceId=0 Inference__CpuUtilizationPercentage=80 Inference__GraphOptimizationLevel=All Inference__ExecutionMode=Parallel Inference__BatchSize=1 Inference__MaxChunkSize=256 ``` ### Hardware | Setting | Default | Description | |---------|---------|-------------| | `ExecutionProvider` | `Auto` | `Auto` uses GPU when running the `-cuda` Worker image, otherwise CPU. `Cpu` forces CPU inference. | | `GpuDeviceId` | `0` | Index of the GPU to use when `ExecutionProvider` resolves to a GPU. | | `CpuUtilizationPercentage` | `80` | Percentage of available CPU cores the runtime uses for inference. Range 1–100. | ### Runtime | Setting | Default | Description | |---------|---------|-------------| | `GraphOptimizationLevel` | `All` | Graph optimization level: `DisableAll`, `Basic`, `Extended`, or `All`. | | `ExecutionMode` | `Parallel` | `Sequential` or `Parallel`. | | `BatchSize` | `1` | Number of text chunks sent to the model per inference call. Range 1–100; values outside the range are clamped. Higher values increase throughput at the cost of memory. | ### Chunking Long text is split into chunks before inference. | Setting | Default | Description | |---------|---------|-------------| | `MaxChunkSize` | `256` | Maximum tokens per chunk. Higher values give the model more context; lower values reduce per-chunk latency. Clamped to `MaxLength` if set higher. | | `MaxLength` | `512` | Hard upper bound on input length in tokens supported by the model. Don't increase beyond what the configured model accepts. | | `MaxWidth` | `12` | Maximum span width in words for a single detected entity. | ## Web server ```bash WebServer__PortNumber=4885 ``` | Setting | Default | Description | |---------|---------|-------------| | `PortNumber` | `4885` | TCP port the Worker listens on. The Manager calls this port only when `ServiceCommunicationType` is `Rest`. | | `MaxFileSizeBytes` | `null` (no limit) | Maximum allowed body size on Worker endpoints. The Worker doesn't accept user uploads, so the limit is normally left unset. | | `MaxConcurrentConnections` | `1000` | Maximum concurrent connections accepted by Kestrel. | The remaining Kestrel limits (`RequestHeadersTimeout`, `KeepAliveTimeout`, `MinRequestBodyDataRateBytesPerSecond`, `MinRequestBodyDataRateGracePeriod`) accept the same values as on the Manager. Refer to [Web server](https://www.pdf-tools.com/docs/smart-redact/references/configuration/manager#web-server) on the Manager configuration page. ## Logging Application logs are written to the console and, optionally, to a file. The fields are top-level (no section prefix). ```bash LogFilePath=./logs/smart-redact-worker-log.txt LogRetentionDays=7 ``` | Setting | Default | Description | |---------|---------|-------------| | `LogFilePath` | — | Path of the rolling-daily log file inside the container. Leave empty to disable file logging. | | `LogRetentionDays` | `7` | Number of days log files are retained on disk. | The minimum log level isn't a separate setting. It's derived from the standard `ASPNETCORE_ENVIRONMENT` environment variable: when set to `Development`, the service emits `Debug`-level logs in a developer-friendly console format; any other value (the default) emits `Information`-level logs in JSON. Use `Development` only for local diagnostics. --- ## Detection(Detection) AI Smart Redact detects sensitive entities in PDF documents by combining deterministic pattern matching with semantic understanding. Each detection request runs through a pipeline that extracts text, runs detectors in parallel, resolves overlapping detections, filters by configured labels, and applies any user-defined exclusions before returning results. ## Detection methods Two complementary detection methods work together: - **Deterministic detection** uses regex-based pattern recognizers and keyword matching. It targets entities with predictable structure such as credit card numbers, IBANs, email addresses, and phone numbers. Format and checksum validators reject malformed matches. Refer to [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers) and [Keyword recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-recognizers). - **Semantic detection** uses a neural Named Entity Recognition model to identify entities that depend on context, such as person names, organizations, and physical addresses. Refer to [Semantic recognizer](https://www.pdf-tools.com/docs/smart-redact/references/detection/semantic-recognizer). Out of the box, AI Smart Redact uses these methods in a hybrid-complementary strategy: each entity type is handled by the method best suited to it. Deterministic recognizers handle structured formats, the semantic model handles contextual entities, and the two don't overlap. This approach delivers the highest precision because format-specific entities benefit from validation that the semantic model can't perform. For benchmark figures, refer to [Detection accuracy](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-accuracy). ## Detection pipeline Each detection request passes through five stages: 1. **Resolve configuration.** The pipeline merges three configuration layers to produce the final request configuration: - Built-in defaults shipped with the service. - A default configuration set in the Human-in-the-Loop (HITL) web application by an administrator. This applies to every detection request unless overridden. - An optional per-request configuration submitted in the Manager API call. Each layer overrides the previous one. Refer to [Detection configuration](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration). 1. **Detect entities.** Pattern recognizers, keyword recognizers, and the semantic recognizer run in parallel against the extracted text. Each pattern recognizer applies its format and checksum validators (refer to [Format and checksum validators](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#format-and-checksum-validators)). The pipeline then filters out any remaining invalid emissions, such as empty labels, out-of-range scores, or negative positions. 1. **Consolidate results.** Entities scoring under the configured score threshold are removed, and overlapping detections are merged according to the rules in [Overlap resolution](#overlap-resolution). 1. **Filter by labels.** Only entities whose label is in the configured `labels` list are kept. 1. **Apply exclusions.** Any entity whose text matches a configured allowlist keyword is removed. Refer to [Keyword exclusions](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-exclusions). The result is a list of entities, each with its text, label, position, and final confidence score. ## Overlap resolution When two detected entities overlap, the consolidator applies one of three rule sets depending on how they overlap. Two entities that merely touch (one ends where the next begins) don't overlap and are both kept. ### Same span When two entities cover the exact same start and end positions, the winner is chosen according to the request's `sameSpanStrategy` field: | Strategy | Winner | |----------|--------| | `deterministicWins` (default) | The deterministic detector wins regardless of score. | | `semanticWins` | The semantic detector wins regardless of score. | | `higherScoreWins` | The entity with the higher score wins. | In all strategies, the higher-scoring entity wins among entities of the same detector type, and the first-detected entity wins on a final tie. With `higherScoreWins`, the deterministic detector wins over the semantic detector on equal score before the first-detected fallback applies. ### Full containment When one entity fully contains another (the longer entity's span includes all of the shorter entity's span and they aren't identical), the longer entity always wins. A longer match is considered more specific and complete. ### Partial overlap When two entities overlap but neither fully contains the other, the higher-scoring entity wins. On a tie, the longer entity wins; on a further tie, the first-detected entity wins. ## Reference pages --- ## Detection accuracy Detection accuracy is measured against the [nvidia/Nemotron-PII](https://huggingface.co/datasets/nvidia/Nemotron-PII) dataset, a synthetic dataset of 50,000 documents annotated across 51 PII label types. Across all 51 label types, AI Smart Redact achieves an adjusted [F1 score](#metric-definitions) of **0.96**. Detection logic is used as shipped — only the semantic recognizer's `entityMapping` is extended so its outputs align with the dataset's label set. ## Out-of-the-box accuracy The evaluation targets every label in the dataset (51 types) using AI Smart Redact's built-in detection configuration. The only change from the shipped defaults is the semantic recognizer's `entityMapping`, which is extended to cover all 51 dataset label types. No custom pattern recognizers, keyword recognizers, or exclusions were added. Evaluation on the full 50,000-sample international test split: | Metric | Raw | Adjusted | |--------|----:|----:| | True positives | 399,967 | 399,967 | | False negatives | 21,979 | 13,016 | | False positives | 40,143 | 18,161 | | **Recall** | **0.9479** | **0.9685** | | **Precision** | **0.9088** | **0.9566** | | **F1** | **0.9279** | **0.9625** | Adjusted scores exclude errors that per-case analysis attributed to the dataset's annotations rather than to the detector. Refer to [Adjusted scores](#adjusted-scores). ### Metric definitions Three standard metrics describe detection quality. They appear throughout this page; the headline F1 score links here. - **Recall**: of all actual sensitive entities in the data, how many did the detector find? A recall of 0.95 means the detector found 95% of the entities that should have been detected. - **Precision**: of all entities the detector flagged, how many were genuinely sensitive? A precision of 0.95 means 95% of the detector's flagged entities were genuine sensitive entities. - **F1**: the harmonic mean of recall and precision, on a scale from 0 to 1. A high F1 means the detector finds most actual entities (high recall) and most of its detections are correct (high precision). ## What this configuration covers The evaluation deliberately stops short of fitting AI Smart Redact to the dataset: - **The built-in pattern recognizers** are used as shipped, with their format and checksum validators. Recognizers for entity types the dataset doesn't include (such as `IBAN`, `MONEY`, and `DOMAIN_NAME`) were disabled for the evaluation; their detections would otherwise be counted as false positives against a dataset that has no annotations for those types. - **The built-in semantic recognizer** is used, with `entityMapping` extended from the default 4 mappings to cover the dataset labels that aren't handled by deterministic pattern recognizers. - **No custom pattern recognizers** were added for dataset-specific labels such as SSN, license plate, national ID, postcode, account number, or employee ID. These types have predictable formats and are best detected by purpose-built recognizers, but adding them would be fitting the configuration to this specific dataset. - **No keyword denylists or exclusions** were added. Some of the 51 dataset labels are deterministic by nature (region-specific identifiers with their own validation rules, such as `SSN`, `LICENSE_PLATE`, and `NATIONAL_ID`), but in this evaluation they're detected only through the semantic model. Adding [custom pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#custom-pattern-recognizers) for those identifier formats typically raises F1 toward the levels seen for built-in deterministic recognizers in this evaluation, where `CREDIT_CARD` reached 0.97, `EMAIL_ADDRESS` 0.99, `MAC_ADDRESS` 1.00, and `URL` 0.99. Actual gains depend on the pattern. To close this gap, use the configuration options described in [Improving accuracy in your environment](#improving-accuracy-in-your-environment). ## Built-in label scores Per-label raw scores from the same evaluation, for the 17 entity types that AI Smart Redact detects out of the box and that the Nemotron-PII dataset annotates: | Entity type | Detection | Recall | Precision | F1 | |-------------|-----------|------:|----------:|---:| | `MAC_ADDRESS` | Deterministic | 0.9991 | 0.9976 | 0.9983 | | `EMAIL_ADDRESS` | Deterministic | 0.9893 | 0.9965 | 0.9929 | | `PERSON` | Semantic | 0.9945 | 0.9880 | 0.9912 | | `GPS_COORDINATE` | Deterministic | 0.9898 | 0.9914 | 0.9906 | | `URL` | Deterministic | 0.9894 | 0.9812 | 0.9853 | | `DATETIME` | Deterministic | 0.9625 | 0.9793 | 0.9708 | | `PHYSICAL_ADDRESS` | Semantic | 0.9728 | 0.9687 | 0.9707 | | `IP_ADDRESS` | Deterministic | 0.9671 | 0.9729 | 0.9700 | | `CREDIT_CARD` | Deterministic | 0.9443 | 0.9968 | 0.9698 | | `DATE` | Deterministic | 0.9423 | 0.9902 | 0.9657 | | `USERNAME` | Semantic | 0.9390 | 0.9830 | 0.9605 | | `VIN` | Deterministic | 0.9182 | 0.9889 | 0.9523 | | `PHONE_NUMBER` | Deterministic | 0.9657 | 0.9326 | 0.9489 | | `ORGANISATION` | Semantic | 0.9581 | 0.9168 | 0.9370 | | `HTTP_COOKIE` | Deterministic | 0.7136 | 0.9688 | 0.8218 | | `BIC_SWIFT` | Deterministic | 0.6701 | 0.9917 | 0.7997 | | `TIME` | Deterministic | 0.6777 | 0.8402 | 0.7503 | The lower raw F1 scores in the table reflect dataset annotation issues rather than detection mistakes. For example, `BIC_SWIFT` recall rises to near-perfect after the cases described in [Adjusted scores](#adjusted-scores) are removed. ## Adjusted scores Each detection error was reviewed individually to determine its cause. A meaningful share of false negatives and false positives traced back to issues in the dataset's annotations. The Nemotron-PII dataset is synthetic, which explains why some annotated values don't conform to real-world format conventions. Most are clear annotation errors. Examples include: - Duration expressions like "30 minutes" annotated as `TIME` rather than as a duration. - BIC/SWIFT codes whose country position doesn't appear in ISO 3166. - Bare years annotated as full dates without a month or day. - Credit card numbers that don't satisfy the Luhn checksum. The remainder are edge cases where the detector and the dataset apply different conventions. For example, the dataset annotates a datetime as separate date and time spans while the detector returns a single datetime entity. Adjusted scores exclude both kinds. The combined impact is significant: about 41% of false negatives and 55% of false positives in the raw count come from these annotation issues rather than from detection mistakes. ## Improving accuracy in your environment The figures shown measure the built-in defaults without any dataset-specific tuning. Detection is fully customizable per request, and customer-tuned configurations consistently produce higher precision and F1 on production documents. To raise accuracy on your documents: - Add [custom pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#custom-pattern-recognizers) for region-specific identifiers (SSN, license plates, national IDs) or domain-specific codes. This is the single biggest lever for higher precision on identifier-style entity types. - Use [keyword exclusions](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-exclusions) to suppress recurring false positives, such as your own company name being detected as `ORGANISATION`. - Adjust `scoreThreshold` to favor precision (raise it) or recall (lower it). - Switch `checksumValidationMode` to `relaxed` if missed entities are more costly than occasional false positives in checksum-validated formats. ## Industry context No universally agreed benchmark exists for evaluating PII detection systems, which makes direct comparisons across products difficult. The closest established field is Named Entity Recognition (NER), where state-of-the-art models routinely report F1 of 0.93–0.94. Those benchmarks are narrower than PII detection: they typically cover 3 or 4 broad entity types (person, location, organization) on clean newswire-style text. PII detection in real-world applications is harder. It covers dozens of heterogeneous entity types (emails, phone numbers, credit card details, national IDs, addresses, and other nuanced personal identifiers), often in messy, domain-specific, or conversational text. It also requires balancing two competing risks: missed sensitive data, which creates privacy and compliance exposure, and over-redaction, which reduces data utility. Reported numbers in the field reflect this difficulty. General-purpose open source PII tools (rule-based and NER hybrids) commonly report F1 in the 0.81–0.85 range on realistic evaluations. Commercial or heavily domain-tuned systems frequently claim 0.91–0.98, though those numbers are often obtained on narrower entity sets, synthetic data, or proprietary benchmarks rather than broad standardized tests. It's worth restating that the Nemotron-PII dataset is synthetic. Real-world PDFs introduce additional challenges that synthetic text doesn't capture: scanned pages where text is extracted through OCR and can include character recognition errors, multi-column or table-heavy layouts that fragment the surrounding context that detection relies on, mixed-language documents, and form-style PDFs where entities appear in field labels and values rather than in flowing prose. The accuracy figures earlier on this page should be read with these factors in mind. --- ## Detection configuration The `detectionConfiguration` object controls how a detection request runs. It's supplied per request through the Manager API and merges on top of the built-in defaults: only the fields you set override the defaults. Property names and enum values use camelCase. Unknown fields don't fail the request; they're returned as validation warnings. For details on submitting a request, refer to [Detection (Manager API)](https://www.pdf-tools.com/docs/smart-redact/references/api/manager/detection). ## Top-level fields ```json { "scoreThreshold": 0.5, "labels": ["EMAIL_ADDRESS", "PHONE_NUMBER"], "languages": ["en"], "regexTimeout": 1000, "checksumValidationMode": "strict", "patternRecognizers": [], "keywordRecognizers": [], "keywordExclusions": [], "semanticRecognizer": null, "disableBuiltInPatternRecognizersForLabels": [], "sameSpanStrategy": "deterministicWins" } ``` | Field | Type | Default | Description | |-------|------|---------|-------------| | `scoreThreshold` | number | `0.5` | Minimum confidence score for an entity to be returned. Values from `0.0` to `1.0`. | | `labels` | string[] | `[]` | Entity types to detect. Empty or omitted means detect all labels enabled in the resolved configuration. The built-in default configuration enables every built-in label. Refer to [Entity types](https://www.pdf-tools.com/docs/smart-redact/references/detection/entity-types) for the full list. | | `languages` | string[] | `[]` | Any of `en`, `de`, `fr`, `it`, `es`, `pt`, `nl`. Empty or omitted resolves to `["en"]`. Affects context words and verbal `DATE` patterns. Refer to [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#language-support). | | `regexTimeout` | integer | `1000` | Milliseconds per regex execution. Allowed values: `0` (use default) or `1` to `1000`. Prevents catastrophic backtracking. | | `checksumValidationMode` | string | `"strict"` | One of `"strict"` or `"relaxed"`. Refer to [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#format-and-checksum-validators). | | `patternRecognizers` | array | `[]` | Custom pattern recognizers appended to the built-in ones. Refer to [`PatternRecognizer` schema](#patternrecognizer-schema). | | `keywordRecognizers` | array | `[]` | Custom denylist recognizers. Refer to [`KeywordRecognizer` schema](#keywordrecognizer-schema). | | `keywordExclusions` | array | `[]` | Allowlist exclusions that suppress matched entities. Refer to [`KeywordExclusion` schema](#keywordexclusion-schema). | | `semanticRecognizer` | object | `null` | Custom entity mapping for the semantic recognizer. When `null` or omitted, the built-in default mapping is used (refer to [Default entity mapping](https://www.pdf-tools.com/docs/smart-redact/references/detection/semantic-recognizer#default-entity-mapping)). Refer to [`SemanticRecognizer` schema](#semanticrecognizer-schema). | | `disableBuiltInPatternRecognizersForLabels` | string[] | `[]` | Labels whose built-in pattern recognizers should be disabled. Useful when replacing them with custom recognizers. | | `sameSpanStrategy` | string | `"deterministicWins"` | One of `"deterministicWins"`, `"semanticWins"`, or `"higherScoreWins"`. Refer to [Overlap resolution](https://www.pdf-tools.com/docs/smart-redact/references/detection/#overlap-resolution). | ## `PatternRecognizer` schema A pattern recognizer detects entities using one or more regex patterns. Custom recognizers are appended to the built-in ones unless you also disable the built-in recognizer for the same label. ```json { "name": "CustomProjectCode", "label": "PROJECT_CODE", "patterns": [ { "name": "ProjectCode", "regex": "\\bPRJ-\\d{4}-[A-Z]{3}\\b", "score": 0.85 } ], "contextWords": ["project", "reference"] } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Recognizer identifier shown in logs. | | `label` | string | Yes | Entity type this recognizer produces. UPPER_SNAKE_CASE. | | `patterns` | RegexPattern[] | Yes | One or more regex patterns. Refer to [`RegexPattern` schema](#regexpattern-schema). | | `contextWords` | string[] | No | Words that boost the confidence score when found near a match. Omit to skip context boosting for this recognizer. | ## `RegexPattern` schema | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Pattern identifier shown in logs. | | `regex` | string | Yes | Regex pattern. Compiled and cached on first use. | | `score` | number | No | Base confidence score on match. Values from `0.0` to `1.0`. | | `allowBacktracking` | Boolean | No | When `false` (the default), the regex runs in a non-backtracking mode. Only set to `true` when your pattern requires features that need backtracking. | ## `KeywordRecognizer` schema A keyword recognizer detects entities by matching against a list of known sensitive terms (a denylist). ```json { "name": "SensitiveTerms", "label": "SENSITIVE_KEYWORD", "keywords": ["confidential", "top secret"], "score": 1.0, "partialMatch": false } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Recognizer identifier. | | `label` | string | Yes | Entity type produced. UPPER_SNAKE_CASE. | | `keywords` | string[] | Yes | Words or phrases to detect. | | `score` | number | No | Confidence score for all matches. Default `1.0`. | | `partialMatch` | Boolean | No | When `false` (the default), case-sensitive whole-word match. When `true`, substring match. | ## `KeywordExclusion` schema A keyword exclusion suppresses detected entities whose text matches a known safe term (an allowlist). ```json { "name": "SafeHostnames", "excludedKeywords": ["localhost", "example.com"], "partialMatch": false } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Exclusion identifier. | | `excludedKeywords` | string[] | Yes | Keywords that, if matching an entity's text, cause it to be excluded. | | `partialMatch` | Boolean | No | When `false` (the default), the entity text must exactly equal a keyword. When `true`, the entity text must contain the keyword as a substring. | ## `SemanticRecognizer` schema ```json { "name": "GlinerLarge", "entityMapping": { "name": "PERSON", "company name": "ORGANISATION", "location address": "PHYSICAL_ADDRESS" } } ``` The example above is illustrative. The shipped default mapping has additional entries; refer to [Default entity mapping](https://www.pdf-tools.com/docs/smart-redact/references/detection/semantic-recognizer#default-entity-mapping) for the full list. | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Fixed identifier for the semantic model. Only `"GlinerLarge"` is accepted; the model itself can't be changed. | | `entityMapping` | object | Yes | Maps semantic-model output labels (key) to standardized entity labels (value, UPPER_SNAKE_CASE). This is the only customizable part of `semanticRecognizer`. | If you don't need to override the entity mapping, omit `semanticRecognizer` entirely. Supplying it solely to repeat the default mapping has no effect on detection results. ## Disable built-in pattern recognizers To replace a built-in pattern recognizer with your own, disable the built-in recognizer for that label and add a custom recognizer for the same label. The following example replaces the built-in `EMAIL_ADDRESS` recognizer with one that only matches addresses on `example.com`: ```json { "disableBuiltInPatternRecognizersForLabels": ["EMAIL_ADDRESS"], "patternRecognizers": [ { "name": "InternalEmail", "label": "EMAIL_ADDRESS", "patterns": [ { "name": "InternalDomain", "regex": "\\b[\\w.+-]+@example\\.com\\b", "score": 0.95 } ] } ] } ``` ## Complete example The following request configuration restricts detection to four labels, raises the score threshold, adds a custom pattern recognizer for project codes, adds a denylist for sensitive terms, and excludes a known false-positive value: ```json { "detectionConfiguration": { "scoreThreshold": 0.7, "labels": ["EMAIL_ADDRESS", "PHONE_NUMBER", "PROJECT_CODE", "PERSON"], "languages": ["en", "de"], "patternRecognizers": [ { "name": "CustomProjectCode", "label": "PROJECT_CODE", "patterns": [ { "name": "ProjectCode", "regex": "\\bPRJ-\\d{4}-[A-Z]{3}\\b", "score": 0.85 } ], "contextWords": ["project", "reference"] } ], "keywordRecognizers": [ { "name": "SensitiveTerms", "label": "SENSITIVE_KEYWORD", "keywords": ["confidential", "top secret"] } ], "keywordExclusions": [ { "name": "SafeAddresses", "excludedKeywords": ["test@example.com"] } ] } } ``` --- ## Entity types An entity type is a label assigned to a detected piece of sensitive information, such as `EMAIL_ADDRESS` or `PERSON`. AI Smart Redact ships with 36 built-in entity types: 32 pattern-based labels detected by regex pattern recognizers, and 4 semantic labels detected by the semantic model. You can also define your own entity types per detection request. ## Pattern-based labels The following 32 labels have built-in pattern recognizers. Each label may match more than one format. For example, `DATE` covers numeric and verbal date formats across more than one language. | Label | What it matches | |-------|-----------------| | `ALPHANUMERIC_CODE` | Mixed letter-digit codes | | `BARCODE` | Product barcodes with checksum validation | | `BIC_SWIFT` | Bank Identifier Codes | | `CREDIT_CARD` | Credit card numbers with Luhn validation | | `CURRENCY_CODE` | ISO 4217 three-letter currency codes | | `DATE` | Calendar dates in common international formats | | `DATETIME` | Combined date-time strings | | `DECIMAL_NUMBER` | Decimal numbers | | `DOMAIN_NAME` | Internet domain names | | `DURATION` | Time durations | | `EMAIL_ADDRESS` | Email addresses | | `FILE_PATH` | Windows and Unix file paths | | `GPS_COORDINATE` | Geographic coordinates | | `HASHTAG` | Social media hashtags | | `HTTP_COOKIE` | HTTP cookie strings | | `IBAN` | International Bank Account Numbers | | `INTEGER_NUMBER` | Integers | | `IP_ADDRESS` | IPv4 and IPv6 addresses | | `ISIN` | International Securities Identification Numbers | | `LEI` | Legal Entity Identifiers | | `MAC_ADDRESS` | Hardware MAC addresses | | `MENTION` | Social media @mentions | | `MONEY` | Monetary amounts | | `NUMERIC_ID` | Digit-only identifiers | | `PERCENTAGE` | Percentage values | | `PHONE_NUMBER` | Phone numbers in common international formats | | `SCIENTIFIC_NUMBER` | Scientific notation numbers | | `TIME` | Times in common formats | | `UNIQUE_IDENTIFIER` | UUID and GUID strings | | `URL` | HTTP, HTTPS, and FTP URLs | | `VAT_NUMBER` | VAT numbers | | `VIN` | Vehicle Identification Numbers | For details on how pattern recognizers work and how to add custom ones, refer to [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers). ## Semantic labels Out of the box, the semantic model detects four entity types: | Label | What it matches | |-------|-----------------| | `PERSON` | Person names | | `ORGANISATION` | Organization and company names | | `PHYSICAL_ADDRESS` | Street addresses and locations | | `USERNAME` | Usernames and handles | The built-in default mapping is a starting point, not a fixed set. You can extend or replace it to detect any entity type the semantic model can recognize. Refer to [Semantic recognizer](https://www.pdf-tools.com/docs/smart-redact/references/detection/semantic-recognizer). ## Confidence scores Every detected entity has a confidence score between 0 and 1. The score reflects how unambiguous the match is. Entities with structurally unique formats and supporting validators score higher; broader patterns that can match many non-PII strings score lower. | Range | Tier | Description | |-------|------|-------------| | 0.90–1.00 | Highest | Structurally unique, almost no false positives | | 0.80–0.89 | High | Distinctive structure, often with checksum validation | | 0.70–0.79 | Moderate | Recognizable format with some ambiguity | | 0.60–0.69 | Lower | Formats that overlap with common text | | 0.50–0.59 | Low | Broad patterns with higher ambiguity | | Under 0.50 | Sub-threshold | Filtered out at the built-in default threshold. Refer to [Sub-threshold patterns](#sub-threshold-patterns). | The built-in default `scoreThreshold` is 0.5. Entities scoring under the threshold are removed from the results. Raise the threshold to favor precision; lower it to favor recall. ## Sub-threshold patterns Some patterns are deliberately configured to score under the built-in default threshold to prevent false positives from highly ambiguous matches. For example, a bare four-digit number could be military time, a year, a PIN, or an arbitrary identifier; the military-time pattern scores under 0.5 and surfaces only when [context boosting](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#context-boosting) raises the score over the threshold. ## Custom entity types You can extend the set of detected entity types in three ways: - Add custom regex patterns. Refer to [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers#custom-pattern-recognizers). - Add a denylist of known sensitive terms. Refer to [Keyword recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-recognizers). - Map more semantic-model outputs to new labels. Refer to [Semantic recognizer](https://www.pdf-tools.com/docs/smart-redact/references/detection/semantic-recognizer#customize-the-entity-mapping). --- ## Keyword exclusions Keyword exclusions form an **allowlist**: configured words or phrases that should never be redacted, even if a detector matched them. Each exclusion removes any already-detected entity whose text matches a configured keyword. Exclusions run as the last stage of the detection pipeline, after all detectors and consolidation. They override any earlier detection, including high-confidence pattern matches. Use exclusions to suppress recurring false positives in your specific document set. To detect domain-specific sensitive terms instead, use [Keyword recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-recognizers) (a **denylist**). ## When to use exclusions Common cases: - Suppress test or placeholder values such as `test@example.com` or `N/A`. - Suppress entity values that the semantic model detects as sensitive but aren't sensitive in your context, such as your own company name. - Suppress any specific keyword you don't want redacted. ## Configuration Add exclusions under `keywordExclusions`: ```json { "detectionConfiguration": { "keywordExclusions": [ { "name": "SafeValues", "excludedKeywords": ["test@example.com", "N/A", "TBD"], "partialMatch": false }, { "name": "InternalDomain", "excludedKeywords": ["example.com"], "partialMatch": true } ] } } ``` For the full schema, refer to [`KeywordExclusion` schema](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration#keywordexclusion-schema). ## Match modes - **Exact match (default).** The entity's full text must equal a keyword. Comparison is case-insensitive. `partialMatch: false`. - **Partial match.** The entity's text must contain a keyword as a substring. `partialMatch: true`. --- ## Keyword recognizers A keyword recognizer is a **denylist**: a configured list of words or phrases that should be detected as sensitive entities when matched in the input text. Matching uses the Aho-Corasick algorithm, which scans for all keywords in a single pass. Use keyword recognizers for terms specific to your domain. To suppress already-detected entities instead, use [Keyword exclusions](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-exclusions) (an **allowlist**). ## Configuration Out of the box, no keyword recognizer is configured. Add your own to detect domain-specific terms: ```json { "detectionConfiguration": { "keywordRecognizers": [ { "name": "SensitiveTerms", "label": "SENSITIVE_KEYWORD", "keywords": ["confidential", "top secret", "internal only"], "score": 1.0 } ] } } ``` For the full schema, refer to [`KeywordRecognizer` schema](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration#keywordrecognizer-schema). ## Match modes - **Exact match (default).** The keyword must appear as a whole token. `partialMatch: false`. - **Partial match.** The keyword can appear as a substring of any word. `partialMatch: true`. Matching is case-sensitive in both modes. --- ## Pattern recognizers A pattern recognizer detects entities by matching the document text against one or more regular expressions. AI Smart Redact ships with built-in recognizers for common entity types such as email addresses, credit card numbers, and phone numbers. Refer to [Entity types](https://www.pdf-tools.com/docs/smart-redact/references/detection/entity-types) for the full list of pattern-based labels. You can also define your own recognizers per detection request. ## How pattern matching works The following steps run inside the **Detect entities** stage of the [detection pipeline](https://www.pdf-tools.com/docs/smart-redact/references/detection/#detection-pipeline). For each recognizer whose label is in the configured `labels` list: 1. Run each regex pattern against the input text. 1. Optionally validate the format of each match. A failed format check rejects the match. 1. Optionally validate a checksum. A failed checksum check either rejects the match or reduces its score, depending on `checksumValidationMode`. 1. Apply context boosting. Words appearing near the match raise the confidence score. 1. Emit a detected entity with the resulting score. ## Built-in pattern recognizers The built-in pattern recognizers cover a broad set of common entity formats and include format and checksum validation where applicable. For example: - `CREDIT_CARD` validates the Luhn checksum. - `IBAN` validates the ISO 7064 Mod 97-10 checksum. - `BIC_SWIFT` validates the country code position against ISO 3166. - `EMAIL_ADDRESS` validates the top-level domain against the IANA list. For the full list of labels and what each one matches, refer to [Entity types](https://www.pdf-tools.com/docs/smart-redact/references/detection/entity-types#pattern-based-labels). ## Format and checksum validators Format and checksum validators reject matches that share the structural shape of the target entity but don't conform to its actual specification. - A **format validator** runs first and always rejects on failure. For example, the email recognizer rejects matches whose top-level domain isn't on the IANA list. - A **checksum validator** runs after the format check. Its behavior on failure depends on the top-level `checksumValidationMode` field: | Mode | Behavior on checksum failure | |------|------------------------------| | `strict` (default) | The match is discarded. | | `relaxed` | The match is kept with its score reduced by 0.30. Context boosting can still raise the reduced score over the threshold. | Use `relaxed` when missing an entity is more costly than a few false positives. For example, when redacting documents where credit card numbers may have been transcribed with errors, `relaxed` mode keeps numbers that fail Luhn validation, at the cost of detecting some random digit sequences as credit cards. ## Context boosting Context boosting raises the confidence score of a pattern match when relevant words appear nearby. This rewards matches found in a semantically meaningful context. For example, the word `email` near an email address. ### How it works 1. The text around the match is tokenized into words. 1. A window of 6 tokens before and 3 tokens after the match is collected. 1. Each `contextWords` entry is matched against the window using whole-word, case-insensitive comparison. Multi-word phrases are matched as consecutive tokens. Longer phrases are matched first; a shorter context word that overlaps an already-matched phrase is skipped. 1. Each unique match adds 0.05 to the confidence score, capped at +0.15 total. 1. The final score is capped at 1.0. ### Parameters | Parameter | Value | |-----------|-------| | Window before match | 6 tokens | | Window after match | 3 tokens | | Boost per context match | +0.05 | | Maximum total boost | +0.15 | | Maximum final score | 1.0 | ### Example For the input `Please send to email: john@example.com for details`: - Entity: `john@example.com` with a base score of 0.80. - Tokens preceding the match (up to 6): `["Please", "send", "to", "email"]`. Matches `email`. - Tokens following the match (up to 3): `["for", "details"]`. No match. - Total boost: 1 × 0.05 = +0.05. - Final score: **0.85**. These numbers are illustrative. Actual base scores vary by recognizer and pattern variant. Context boosting applies only to pattern recognizers. Keyword and semantic recognizers don't perform context boosting. ## Language support The detection request's `languages` field controls language-aware behavior in pattern recognizers: - **Context words.** Each selected language adds its own context word vocabulary on top of the universal context words. Universal context words such as `iban`, `visa`, and `dob` are always loaded. - **`DATE` pattern coverage.** Verbal date patterns are generated per selected language. For example, `January` matches in English, `Januar` in German, and `janvier` in French. `DATE` is the only label whose pattern coverage depends on `languages`. Supported languages: English (`en`), German (`de`), French (`fr`), Italian (`it`), Spanish (`es`), Portuguese (`pt`), and Dutch (`nl`). ## Custom pattern recognizers Add a custom pattern recognizer to detect entity types not covered by the built-in set. Custom recognizers are appended to the built-in ones unless you also disable the built-in recognizer for the same label. ```json { "detectionConfiguration": { "patternRecognizers": [ { "name": "CustomProjectCode", "label": "PROJECT_CODE", "patterns": [ { "name": "ProjectCode", "regex": "\\bPRJ-\\d{4}-[A-Z]{3}\\b", "score": 0.85 } ], "contextWords": ["project", "code", "reference"] } ] } } ``` For the full schema, refer to [`PatternRecognizer` schema](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration#patternrecognizer-schema). ## Disable a built-in recognizer To replace a built-in pattern recognizer for a label, set `disableBuiltInPatternRecognizersForLabels` to disable the built-in one and add a custom recognizer for the same label: ```json { "detectionConfiguration": { "disableBuiltInPatternRecognizersForLabels": ["PHONE_NUMBER"], "patternRecognizers": [ { "name": "InternalPhone", "label": "PHONE_NUMBER", "patterns": [ { "name": "InternalExtension", "regex": "\\bx\\d{4}\\b", "score": 0.85 } ] } ] } } ``` ## Performance and safety - **Compilation and caching.** Each regex pattern compiles on first use and is cached for subsequent matches. - **Backtracking protection.** Custom patterns run in non-backtracking mode by default. Set `allowBacktracking: true` only when your pattern requires it. Backtracking patterns can run slowly on adversarial inputs, and each match runs until it completes or hits `regexTimeout`. - **Execution timeout.** The `regexTimeout` field caps a single regex execution at the configured number of milliseconds (default 1000). Matches that exceed the timeout are aborted to prevent stalled requests. --- ## Semantic recognizer The semantic recognizer detects entities by understanding the context in which they appear, rather than by matching predefined formats. AI Smart Redact uses a neural Named Entity Recognition (NER) model for this purpose. Semantic detection is best suited for entities whose form varies too widely for regex matching, such as person names, organization names, and physical addresses. For format-specific entities such as credit card numbers, IBANs, and dates, use [Pattern recognizers](https://www.pdf-tools.com/docs/smart-redact/references/detection/pattern-recognizers) instead. ## Default entity mapping The semantic model emits its own output labels. Out of the box, these are mapped to four entity labels: | Label | Source labels | |-------|---------------| | `PERSON` | `name`, `first name`, `last name` | | `ORGANISATION` | `company name`, `organization name` | | `PHYSICAL_ADDRESS` | `location address` | | `USERNAME` | `user name` | ## Customize the entity mapping The semantic model can recognize a wide range of entity types beyond the defaults. The model itself isn't user-configurable; only the `entityMapping` field can be changed. Override `semanticRecognizer.entityMapping` to add new entity types or change the mapping. Each entry maps a model output label (the key) to the entity label that should be emitted (the value). The model accepts arbitrary descriptive phrases as output labels. There's no fixed vocabulary, so you can ask for any concept the model can interpret. Avoid choosing labels that overlap with other semantic mappings (for example, `city` would compete with the built-in `location address` mapped to `PHYSICAL_ADDRESS`) or with deterministic recognizers (for example, `date of birth` would compete with the `DATE` pattern recognizer, which detects dates more reliably). The following example extends the built-in default mapping to detect nationalities and occupations as separate labels: ```json { "detectionConfiguration": { "semanticRecognizer": { "name": "GlinerLarge", "entityMapping": { "name": "PERSON", "first name": "PERSON", "last name": "PERSON", "company name": "ORGANISATION", "organization name": "ORGANISATION", "location address": "PHYSICAL_ADDRESS", "user name": "USERNAME", "nationality": "NATIONALITY", "occupation": "OCCUPATION" } } } } ``` When you customize the mapping, also include the new entity labels in the request's `labels` field. Otherwise the detected entities are removed by the label-filtering pipeline stage. For the full schema, refer to [`SemanticRecognizer` schema](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-configuration#semanticrecognizer-schema). ## Inference settings Semantic-model inference is tuned through Worker configuration: | Setting | Default | Description | |---------|---------|-------------| | `Inference.MaxChunkSize` | 256 tokens | Maximum chunk size sent to the model. Long text is split into chunks of this size before inference. | | `Inference.MaxLength` | 512 tokens | Model token-length limit. Don't increase beyond the model's supported context window. | | `Inference.BatchSize` | 1 | Number of chunks processed per inference call. Higher values increase throughput at the cost of memory. | For where to set these values, refer to [Worker configuration](https://www.pdf-tools.com/docs/smart-redact/references/configuration/worker#inference). ## Limitations Semantic detection can produce false positives for entities the semantic model recognizes correctly but that aren't sensitive in your context. Common cases include: - Well-known public entities such as government bodies or sports teams detected as `ORGANISATION`. - Cities, counties, states, or postcodes detected as `PHYSICAL_ADDRESS` when they appear in address-like context. - Words that resemble names, such as colors, demonyms, or United States state names, detected as `PERSON`. Mitigate these by adding [keyword exclusions](https://www.pdf-tools.com/docs/smart-redact/references/detection/keyword-exclusions) for the specific terms that recur in your documents. For accuracy figures, refer to [Detection accuracy](https://www.pdf-tools.com/docs/smart-redact/references/detection/detection-accuracy). --- ## Redaction(References) AI Smart Redact redacts sensitive entities in PDF documents by removing the marked content and rebuilding the document. Every entity in a redaction request is removed, not just visually masked. Each request takes a source PDF and a list of redaction areas: rectangles on a page that mark where each entity to redact appears. ## True redaction by reconstruction The output PDF is built from scratch. Only content that the redaction engine fully understands and that isn't marked for redaction carries over to the new document. Anything else is dropped, including hidden data that wasn't part of the visible page: document metadata, bookmarks, annotations, and embedded files. Page count, page sizes, and the positioning of all unredacted content are preserved. Only the content inside the redaction areas is removed. AI Smart Redact doesn't just draw a black rectangle over redacted content. The text, images, vector graphics, and any OCR text layers inside each redaction area are structurally removed from the page content streams, just like the visible text on top of them. As a result, redacted text can't be copied from the content stream, and no parallel hidden layer preserves the original content. ## Performance Redaction is fast and runs independently of the detection step, with up to four concurrent jobs per Worker by default. Redaction time scales with document size rather than the number of entities to redact. ## Unhandled features The redaction engine doesn't yet support every PDF feature. Most page structures are unconditionally rebuilt or removed during redaction, but some features have to stay in the document so the redaction engine doesn't break the document's integrity. The following PDF features fall into that group: - Marked Content (accessibility tagging and structural marks inside page content streams) isn't removed. Structures such as `ActualText` can leak sensitive information. - Optional Content Groups (OCG, also known as "Layers") aren't considered separately. They are redacted as if they were normal content. - OutputIntent in ICC profiles and Font or FontDescriptor metadata aren't stripped. These are theoretical surfaces; while the data inside is custom, this data is usually not sensitive in any way. OCR text layers and other on-page text are removed only where a redaction area covers them, the same as visible text. ### Invisible content The redaction engine doesn't perform additional sanitization passes for content that the reviewer can't see. Out-of-bounds content falls into this category: - Text, images, and vector paths positioned outside the page bounds. A redaction area placed there still removes the content, but the reviewer never sees out-of-bounds content in the viewer, so the reviewer doesn't select it for redaction during review. ### Reporting new findings If you encounter a PDF where AI Smart Redact leaves content that the redaction engine should have removed, [open a support request](https://www.pdf-tools.com/docs/support/) with a sample. Real-world feedback on issues encountered with PDF files guides further development of the product, and the redaction engine's coverage can expand as you report edge cases. --- ## Release notes(Smart-redact) Learn about the changes, additions, and fixes in AI Smart Redact. ## Version 1.0.0 05 May 2026 ### Added - AI Smart Redact detects and redacts Personally Identifiable Information (PII) from PDF documents. Send PDFs through the REST API or upload them through the Human-in-the-Loop (HITL) web interface. Both workflows return detection results with entity locations, and you can apply redactions to create sanitized documents. The HITL interface lets reviewers inspect detected PII before applying redactions. - Deterministic detection through two methods: - **Pattern detection** uses compiled regular expressions for structured formats like credit cards, IBANs, and email addresses. Patterns include checksum validation (Luhn, ISO 7064) where applicable. - **Keyword detection** uses the Aho-Corasick algorithm for fast matching of known sensitive terms from configurable denylists. You can also configure allowlists to suppress false positives for specific terms. - Semantic detection through an AI model that identifies context-dependent entities like person names, organizations, and physical addresses. You can configure entity labels at runtime through detection configurations. - 36 built-in entity labels: - Deterministic (pattern detection): - Financial: `CREDIT_CARD`, `IBAN`, `BIC_SWIFT`, `MONEY`, `BARCODE`, `ISIN`, `LEI`, `VAT_NUMBER` - Identification: `UNIQUE_IDENTIFIER`, `VIN`, `NUMERIC_ID`, `ALPHANUMERIC_CODE`, `CURRENCY_CODE` - Contact: `EMAIL_ADDRESS`, `PHONE_NUMBER`, `DOMAIN_NAME`, `URL` - Network: `IP_ADDRESS`, `MAC_ADDRESS`, `HTTP_COOKIE` - Location: `GPS_COORDINATE`, `FILE_PATH` - Temporal: `DATE`, `DATETIME`, `TIME`, `DURATION` - Numbers: `DECIMAL_NUMBER`, `INTEGER_NUMBER`, `SCIENTIFIC_NUMBER`, `PERCENTAGE` - Social: `MENTION`, `HASHTAG` - Semantic (AI-powered, default configuration): `PERSON`, `ORGANISATION`, `PHYSICAL_ADDRESS`, `USERNAME` - Context-aware confidence boosting. When context words appear near pattern matches, the detector increases confidence scores. For example, if "email" appears near an email address, confidence increases. Context words are available in seven languages: English, German, French, Italian, Spanish, Portuguese, and Dutch. - Detection configurations let you create and manage detection profiles that control score thresholds, enabled entity labels, languages, custom pattern recognizers, keyword lists, and exclusion rules. A starter template provides recommended defaults for new configurations. - REST API for job processing. Upload PDF files, start detection or redaction jobs, and poll for results. The API uses asynchronous job processing, so you can send multiple documents and retrieve results when processing completes. - HITL web interface for interactive document review and redaction. Upload PDFs, view detected entities with confidence scores in an integrated PDF viewer, and accept or reject individual redaction suggestions before generating the final redacted document. Administrators can manage users and create detection configurations with a live testing panel to preview results against sample documents. - User management and authentication. The HITL interface includes role-based access control. Administrators can create users, reset passwords, and manage account activation. - API key authentication for programmatic access to upload files, check job statuses, and download redacted documents. Keys support expiration dates. - Audit logging. All authentication events, user management actions, configuration changes, and file operations (upload, redaction, and download) are recorded in an append-only audit trail for compliance and troubleshooting. - Encryption at rest. Uploaded files are encrypted with AES-256-GCM using configurable keys. The service supports key rotation and Data Encryption Key (DEK) token caching with Redis. - Docker deployment. Deploy AI Smart Redact as Docker containers using the Docker Compose configurations from the samples repository. The service supports both CPU and GPU deployments; GPU deployment uses NVIDIA CUDA and provides faster inference for semantic detection. For deployment examples and API usage samples, refer to the [AI Smart Redact samples repository](https://github.com/pdf-tools/smart-redact-samples). - OpenTelemetry observability. The service exports traces, metrics, and structured logs through OpenTelemetry. Connect to Grafana LGTM, Seq, Jaeger, or any OpenTelemetry-compatible backend for monitoring and diagnostics. --- ## Pdftools Technical Support We're happy to help with any questions about our products. We've been leading the way in PDF technology for 20+ years, so you can count on the developer experience and support you need. :::info[Need help?] If you encounter an issue with your Pdftools product: - Search the **product documentation** with the error code or message. - Check if a **newer version** of the software is available in the [Pdftools Portal](https://portal.pdf-tools.com/). - If this doesn't solve your issue, open a support request. ## Open a support request The **Support** tab in the [Pdftools Portal](https://portal.pdf-tools.com/) lets you open support requests, access documentation resources, and contact your dedicated customer success manager. When you open a support request, indicate: - The product affected. - The version installed. - Any support logs (if available). To open a support request: 1. Log in to the [Pdftools Portal](https://portal.pdf-tools.com/). 1. Select **Support** in the sidebar. 1. Select **Open a support request**. 1. Fill in the support form and attach any necessary files. 1. Select **Submit**. Open a support request Submit a ticket through the Pdftools Portal for technical assistance. ↗ After you submit the form, your support request appears on the **Support requests** tab. To share files that exceed the attachment size limit, use the **Files** tab. Select **Upload** to upload files that your Pdftools support team can access. --- :::note[Feedback on our docs?] Missing information from the docs? Didn't quite cover your specific use case? Send ideas and suggestions through the [Contact page](https://www.pdf-tools.com/contact/). --- ## Release management Learn about versioning of the Pdftools products and their supported releases. ## Versioning The Pdftools products use [semantic versioning](https://semver.org/). The version is marked as MAJOR.MINOR.PATCH. For example, a product with version 5.1.1 indicates a major version 5, a minor version 1, and a patch version 1. ## Release types of the Pdftools products There are two release types in the Pdftools products: - **Feature release**: Receives regular updates with new functionalities and bug fixes. As a result, feature releases get stability improvements, new features, and product advancements. - **Long-term support (LTS)** release: Receives regular patches with bug fixes for two years. The LTS release involves extended test and integration processes. As a result, this type of release focuses mostly on long-term stability. See the following table for an overview of the Pdftools product releases: | Release type | Frequency | Content | Patch support | | --------------- | --------- | -------------------------------------------------------------------------------------- | ---------------------------------------- | | Feature release | Monthly | Stability improvementsNew features and product advancements | Provided until the next feature release. | | LTS | Yearly | Stability improvementsBug fixes | Provided for two years. | ### Supported LTS product releases The following table doesn't intentionally include the third number of the semantic versioning standard. LTS releases only receive patches, meaning the last number is updated with each released patch. | Product | LTS versions | Supported until | | ---------------------- | ------------ | --------------- | | All 3-Heights products | 6.27 | End of 2025 | | PDF Toolbox SDK | 4.4 | End of 2025 | | PDF Viewer SDK | 4.3 | May 2027 | | Conversion Service | 5.7 | End of 2026 | | Conversion Service | 4.8 | End of 2025 | --- ## Toolbox add-on overview The Toolbox add-on is a low-level PDF manipulation library. With the Toolbox add-on, you can assemble the bits and pieces that make up a PDF. Create new content, set metadata, and manipulate existing PDF content. Even though it’s called an “add-on,” it is not an extension of the Pdftools SDK. Instead, it is a separate SDK focused on detailed, fine-grained PDF creation and modification. Meanwhile, the Pdftools SDK is for high-level PDF processing. The Toolbox add-on is made for engineering teams that need: - **Fine-grained control** over PDF structure and content - **Programmatic PDF creation** from scratch, including pages, text, and images - **Content extraction and manipulation** at the element level - **Metadata management** for document properties and custom attributes - **Page-level operations** such as copying, reordering, and assembling pages from multiple sources - **High-performance** native libraries with a small **memory footprint** and **predictable runtime behavior** ## What the Toolbox add-on doesn't include The Toolbox add-on is a low-level PDF manipulation library that doesn't include: - Viewer components. Use the [PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer) for viewing features. - Job orchestration, distribution for scaling, UI, or low-code-driven document processing pipelines. Use the [Conversion Service](https://www.pdf-tools.com/docs/conversion-service) instead. - High-level PDF processing pipelines such as PDF/A conversion, optimization, or rendering. Check out the [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) instead. - Intelligent Document Processing (IDP) and other machine learning document intelligence features. --- ## API references and technical notes(Api-references) These sections provide links for the Toolbox add-on API references. - [C API](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/cdoc/files.html) - [Java API](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/javadoc/index.html?overview-summary.html) - [.NET API](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/dotnet/html/R_Project_API_Reference.htm) - [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/pydocs/index.html) ## Technical notes Find an overview of the technical details about the Toolbox add-on for various programming languages on the [Technical notes](https://www.pdf-tools.com/docs/toolbox-add-on/api-references/technical-notes/) overview page. --- ## Technical notes(Technical-notes) --- ## C technical notes(Technical-notes) Learn about the specifics and technical details of the Toolbox add-on for C. **tip: For the full API reference for the Toolbox add-on, see the [C API reference](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/cdoc/files.html).** ## Namespaces, classes, and methods The C programming language uses function prefixes and handles instead of namespaces and classes to model interfaces. All types in the Toolbox add-on, including handles and enumerations, are defined in the `PdfTools_Types.h` header file. Types have the following naming scheme: ``` T‹prefix›_‹type› ``` where `‹prefix›` is a shortened namespace prefix and `‹type›` is the name of the type. Similarly, the Toolbox add-on defines functions, collected in header files `Pdftools_‹sub-prefix›.h` with the following naming convention: ``` ‹prefix›_‹type›_‹name› ``` where `‹type›` is the class name and `‹name›` is the name of the function. ## Objects Objects in the Toolbox add-on for C package interface are represented by object handles. Some types are disposable, which means you must close them by calling `‹prefix›_‹type›_Close`. Release all other types by calling `‹prefix›_Release`. ### Type casting The Toolbox add-on uses a class hierarchy to model parent-child relationships, where a parent type `T‹prefix›_‹parentType›` can have derived child types `T‹prefix›_‹childType›`. Downcasting is necessary, for example, to call the functions of an object's parent class. In this case, you can cast a handle of the child type using a C-style cast: ``` (T‹prefix›_‹parentType›*)pChildTypeHandle ``` Upcasting is also possible using a C-style cast. Before casting, you can determine the child type using the `GetType` function of the parent class: ``` (T‹prefix›_‹parentType›Type) iChildType = ‹prefix›_‹parentType›_GetType(pParentTypeHandle); ``` ## Properties Properties are modeled with setter and getter functions `‹prefix›_‹type›_Get‹name›` and `‹prefix›_‹type›_Set‹name›`, where `‹name›` is the name of the property. ## Error handling After calling a function, detect any errors as follows: 1. If the return type of the function is `BOOL` or a pointer, and the return value is `FALSE` or `NULL` respectively, call the `PdfTools_GetLastError` function. If this method returns `ePdfTools_Error_Success`, then no error occurred and the return value is legitimate. 2. If the return type of the function isn't a Boolean or a pointer, call the `PdfTools_GetLastError` function. If this method returns `ePdfTools_Error_Success`, then no error occurred. To get more information about the error, use the `PdfTools_GetLastErrorMessage` function. ## Strings All functions involving strings are provided in two different flavors: - UTF-16 function with suffix `W` that uses `WCHAR` as the parameter type. - Multi-byte character set function with suffix `A` that uses `char` as the parameter type. The concrete character set that's used depends on the platform: - On Windows, the current ANSI code page (`CP_ACP`) is assumed. - On Linux or macOS, the current C encoding (`LC_CTYPE`) is used. In addition to the function names with suffix, there's a macro without suffix for each function pair. The macro resolves to one of the function variants: - `W` if `_UNICODE` is defined. - `A` if `_UNICODE` isn't defined. :::info[Example] Signature example of an API string property setter, where `‹name›` stands for the property’s name: ```c // Multibyte encoding: void ‹prefix›_‹type›_Set‹name›A(T‹prefix›_‹type›* pHandle, const char* szString); // UTF-16: void ‹prefix›_‹type›_Set‹name›W(T‹prefix›_‹type›* pHandle, const WCHAR* szString); #ifdef _UNICODE #define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›W #else #define ‹prefix›_‹type›_Set‹name› ‹prefix›_‹type›_Set‹name›A #endif ``` ### String return values In C, functions that return a string have a special behavior. Instead of returning the string, those functions take a buffer and a size as the last parameters and write into that buffer. The return value is the amount of data written to the buffer. To determine the required buffer size, call the function with `NULL` as the buffer argument. Calling a function with a buffer size that's too small results in an error. Multibyte character set functions (with the suffix `A`) that return a string may fail to correctly encode the string in the encoding of the current operating system. In this case, the return value is 0 and no error code is set. To prevent such failures, use the UTF-16 (`W`) functions on Windows or use operating systems with a Unicode code page. :::info[Example] Signature example usage of an API string property getter: ```c size_t PdfTools_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize); ``` ```c size_t nBufferSize = PdfTools_Sdk_GetVersionA(NULL, 0); char* pBuffer = malloc(nBufferSize * sizeof (char)); nBufferSize = PdfTools_Sdk_GetVersionA(pBuffer, nBufferSize); ``` ## Streams Streams use a set of callbacks and a context pointer, grouped in a struct `TPdfToolsSys_StreamDescriptor`. An implementation for `FILE*` is provided in the header file `PdfTools_PdfToolsSys.h`. Search for the `PdfToolsSysCreateFILEStreamDescriptor` function. ## Arrays In C, arrays work similarly to strings. Array parameters consist of a pointer to a buffer and a size parameter specifying the number of array elements. Functions that return an array take a buffer and a size as last parameters and write into that buffer. The return value is the number of elements written to the buffer. A return value of `(size_t)-1` indicates an error. To determine the required buffer size, call the function with `NULL` as the buffer argument. Calling the function with a buffer size that's too small results in an error. ## Lists Every list type `T‹prefix›_‹list›` provides a subset of the following functions, where `T‹prefix›_‹eltype›` stands for the type of the contained elements: | Function | Description | Possible errors | | ------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | | `int` `‹prefix›_‹list›_GetCount(T‹prefix›_‹list›*)` | Get the number of elements in the list. | `ePdfTools_Error_IllegalState` | | `T‹prefix›_‹eltype›*` `‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)` | Get an element of the list. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_UnsupportedOperation` | | `BOOL` `‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)` | Add an element to the end of the list. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_UnsupportedOperation` | ## Maps A map is a dictionary with unique keys and associated values. Currently, the only key type in all maps in the API is a string. Every map type `T‹pre›_‹map›` provides a subset of the following functions, where `T‹pre›_‹eltype›` is the type of the contained values. | Function | Description | Possible errors | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `int` `‹pre›_‹map›_GetSize(T‹pre›_‹map›*)` | The number of key-­value pairs in the map. | `ePdfTools_Error_IllegalState` | | `int` `‹pre›_‹map›_GetBegin(T‹pre›_‹map›*)` | Get the position of the first entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. Use `‹pre›_‹map›_GetNext` to get the position of the next entry. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetEnd(T‹pre›_‹map›*)` | Get the end position of the map. This position doesn't correspond to an actual entry in the map. It must be used to determine whether the end of the map has been reached when using `‹pre›_‹map›_GetBegin` and `‹pre›_‹map›_GetNext`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetNext(T‹pre›_‹map›*, int it)` | Get the position of the next entry in the map. The order of the entries is arbitrary and not significant. If the returned position differs from `‹pre›_‹map›_GetEnd`, then the position can be used to retrieve the map entry with `‹pre›_‹map›_GetKey` and `‹pre›_‹map›_GetValue`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation` | | `int` `‹pre›_‹map›_GetA(T‹pre›_‹map›*, const char* szKey)` | Get the position of a key in the map. If no error occurred, then the position can be used to get the corresponding value with `‹pre›_‹map›_GetValue`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument`, `ePdfTools_Error_NotFound` | | `size_t` `‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)` | Get the key of the entry given a position. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)` | Get the value of the entry given a position. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_SetA(T‹pre›_‹map›*, const char* szKey, T‹pre›_‹eltype›* pValue)` | Set the value of an entry for a given key. This operation invalidates all positions previously returned by `‹pre›_‹map›_GetBegin`, `‹pre›_‹map›_GetEnd`, `‹pre›_‹map›_GetNext`, and `‹pre›_‹map›_Get`. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_SetValue(T‹pre›_‹map›*, int it, T‹pre›_‹eltype›* pValue)` | Set the value of the entry at a position in the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_Clear(T‹pre›_‹map›*)` | Remove all entries from the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | | `BOOL` `‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)` | Remove the entry at a position in the map. | `ePdfTools_Error_IllegalState`, `ePdfTools_Error_UnsupportedOperation`, `ePdfTools_Error_IllegalArgument` | --- ## .NET technical notes(Technical-notes) Learn about specifics of the .NET interface of the Toolbox add-on. **tip: For the full API reference for the Toolbox add-on, see the [.NET API reference](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/dotnet/html/R_Project_API_Reference.htm).** ## IDisposable objects Objects that must be closed explicitly (for example, `PdfTools.Toolbox.Pdf.Document` or `PdfTools.Toolbox.Pdf.Content.ContentGenerator`) implement the `IDisposable` interface. Instead of calling `Dispose()` directly, use the `using` statement: ``` using (Document document = ...) { ... } // document.Dispose() is called implicitly here ``` ## Error handling Errors are reported using exceptions. Where applicable, the Toolbox add-on maps errors to corresponding native exception classes, such as `System.ArgumentException`, `System.InvalidOperationException`, `System.NotSupportedException`, or `System.IO.IOException`. The remaining errors are modeled using exception classes that inherit from a base class `PdfToolsException`. ## Streams The native stream interface `System.IO.Stream` is used. ## Lists and iterables The API uses different concepts for returning collections of elements depending on the context: - Lists (`System.Collections.Generic.IList`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible. - Iterables (`System.Collections.Generic.IEnumerable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements. ## Maps Maps implement the native dictionary interface `System.Collections.Generic.IDictionary`. ## Namespace The Toolbox add-on uses the namespace `PdfTools.Toolbox`. **note: We recommend using a custom, company-specific namespace for your code.** Using the `PdfTools.Toolbox` namespace like the Toolbox add-on can lead to problems with ambiguous class names. --- ## General technical notes(Technical-notes) This documentation explains how the Toolbox add-on interacts with your local operating system to [locate fonts](#locate-fonts), [locate color profiles](#locate-color-profiles), and store [temporary files](#temporary-files-directory) and [cache files](#cache-directory). ## Locate fonts Some of the Toolbox add-on 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). ### Font directories The location of the font directories depends on the operating system. The Toolbox add-on 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. #### Install 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 Toolbox add-on 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\\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 `PdfTools_Toolbox.dll` resides. The Toolbox add-on traverses the directories recursively in this order. #### Install 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](http://corefonts.sourceforge.net/). For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq). **The font directories for Linux are:** 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 Toolbox add-on traverses the directories recursively in this order. #### Install 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](http://corefonts.sourceforge.net/). For more information on Microsoft core fonts and licensing, see [Font redistribution FAQ for Windows](https://docs.microsoft.com/en-us/typography/fonts/font-faq). **The font directories for macOS are:** 1. `/System/Library/Fonts` 2. `/Library/Fonts` The Toolbox add-on traverses the directories recursively in this order. ### Add custom font lookup paths In addition to the default directories, developers can specify custom font lookup paths using these methods: * C: [Ptx_Sdk_AddFontDirectoryA](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/cdoc/_pdf_tools___toolbox___ptx_8h.html#aa0f64db2e67b47e2bb92c7eed6dfa8a3) or [Ptx_Sdk_AddFontDirectoryW](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/cdoc/_pdf_tools___toolbox___ptx_8h.html#aa51f83f3207b3080ca0fb8b3ce795704) * C#: [Sdk.AddFontDirectory](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/dotnet/html/M_PdfTools_Toolbox_Sdk_AddFontDirectory.htm) * Java: [Sdk.addFontDirectory](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/javadoc/com/pdftools/toolbox/Sdk.html#addFontDirectory(java.lang.String)) * Python: [Sdk.add_font_directory](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/pydocs/_autosummary/pdftools_toolbox.sdk.html#pdftools_toolbox.sdk.Sdk.add_font_directory) ### 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 Toolbox add-on. 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 `/Installed Fonts` of the cache directory. ## Locate color profiles If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the Toolbox add-on. If no specific color profiles are set, default profiles are used. By default, the Toolbox add-on 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: **Windows:** 1. `%SystemRoot%\System32\spool\drivers\color` 2. directory `Icc`, which must be a direct subdirectory of where the `PdfTools_Toolbox.dll` resides. **Linux:** 1. `$PDF_ICC_PATH` if the environment variable is defined 2. the current working directory **macOS:** 1. `$PDF_ICC_PATH` if the environment variable is defined 2. the current working directory 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: - [Pdftools color profiles](http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip) - [ICC sRGB profiles](http://www.color.org/srgbprofiles.html) - [Adobe ICC Profiles](https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html) ## Special directories The Toolbox add-on 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 Toolbox add-on determines the directory by checking for the existence of environment variables in this order and using the first path found: **Windows:** 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. **Linux:** 1. The path specified by the `$PDFTMPDIR` environment variable. 2. The path specified by the `$TMP` environment variable. 3. The `/tmp` directory. **macOS:** 1. The path specified by the `$PDFTMPDIR` environment variable. 2. The path specified by the `$TMP` environment variable. 3. The `/tmp` directory. ### Cache directory The cache directory is used for data that persists and is shared between different invocations of a program. The Toolbox add-on 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 Toolbox add-on can't create or update caches, leading to significantly decreased performance. **Windows:** If the user has a profile: ``` %LOCAL_APPDATA%\PDF Tools AG\Caches ``` If the user has no profile: ``` \PDF Tools AG\Caches ``` **Linux:** If the user has a home directory: ``` ~/.pdf-tools/Caches ``` If the user has no home directory: ``` /pdf-tools/Caches ``` The `` refers to the [directory for temporary files](#temporary-files-directory). **macOS:** If the user has a home directory: ``` ~/.pdf-tools/Caches ``` If the user has no home directory: ``` /pdf-tools/Caches ``` The `` refers to the [directory for temporary files](#temporary-files-directory). --- ## Java technical notes(Technical-notes) Learn about technical details of the Toolbox add-on for Java. **tip: For the full API reference for the Toolbox add-on, see the [Java API reference](https://api-reference.pdf-tools.com/pdfsdkxt/1.12/javadoc/index.html?overview-summary.html).** ## AutoCloseable objects Objects that must be closed explicitly (for example, `com.pdftools.toolbox.pdf.Document` or `com.pdftools.toolbox.pdf.content.ContentGenerator`) implement the `java.lang.AutoCloseable` interface. Instead of calling `close()` directly, use the "try-with-resources" statement: ``` try (Document document = ...) { ... } // document.close() is called implicitly here ``` ## Properties Properties are modeled with setter and getter methods. ## Error handling Errors are reported using exceptions. Where applicable, the Toolbox add-on maps errors to corresponding native runtime exceptions, such as `java.lang.IllegalArgumentException`, `java.lang.IllegalStateException`, `java.lang.UnsupportedOperationException`, or `java.io.IOException`. The remaining errors are modeled using exception classes that inherit from a base class `PdfToolsException`. ## Streams The native stream interfaces can't be used because they're lacking two important features: - The PDF file format is based on random access. Native Java streams have only limited support for this. - The ability to read from an output stream is crucial for processing large files. Instead, a custom stream interface `com.pdftools.toolbox.sys.Stream` is provided. A `FileStream` implementation for files is provided, backed by `java.io.RandomAccessFile`. For in-memory processing, a `MemoryStream` implementation is provided. ## Lists and iterables The API uses different concepts for returning collections of elements depending on the context: - Lists (`java.util.List`) are used when the elements are already in memory and random access is possible. Depending on the context, manipulation (add, remove, and so on) might also be possible. - Iterables (`java.util.Iterable`) are used when elements are retrieved on demand. They don't allow random access, but only allow iterating through the elements. ## Maps Maps implement the native Java map interface `java.util.Map`. ## Package The Toolbox add-on uses the package `com.pdftools.toolbox`. **note: We recommend using a custom, company-specific package for your code.** Using the `com.pdftools.toolbox` package like the Toolbox add-on can lead to problems with ambiguous class names. --- ## Toolbox add-on code samples :::caution[Code samples temporarily unavailable] The code sample repositories for Pdftools SDK and Toolbox add-on are offline. We apologize for the inconvenience. If you need a code sample, [contact support](https://www.pdf-tools.com/docs/support/#open-a-support-request). Find Toolbox add-on code samples on GitHub and on Google Colab. Clone a GitHub repository to get the code, test Toolbox add-on features using sample PDFs included in each example, and check a per-sample README with instructions on how to run the sample. You can also open Jupyter notebooks in Google Colab to run code examples in your browser without a local setup. New to the Toolbox add-on? Start with `ImageExtraction` or `AddText`, the entry-point samples used in the [getting-started guides](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/). :::note[Colab lists notebooks for two SDKs] The Colab dialog opens the shared `components-code-sample-hub` repository, which holds notebooks for both the Pdftools SDK and the Toolbox add-on SDKs. The dialog has no built-in filter. To find Toolbox add-on notebooks: 1. Open your browser's find-on-page bar with `Cmd`+`F` on macOS or `Ctrl`+`F` on Windows and Linux. 1. Enter the prefix `pdftools_toolbox_`. 1. Click a matching notebook to open it in Colab. --- ## Getting started with the Toolbox add-on Welcome to the Toolbox add-on getting started guides. The Toolbox add-on is a library for developers who need low-level access to the content of PDF files. Guides for C, .NET, Java, and Python explain how to work with a code example, and then walk you through the steps necessary to integrate the Toolbox add-on into your application. ## Trial license You can use the same license key for the Pdftools SDK, the Pdftools SDK Shell Tool, and the Toolbox add-on. The Pdftools SDK and the Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. --- ## Get started with C(Getting-started) This guide walks you through the steps to use a code example, and then explains how to integrate the Toolbox add-on into your application with the C programming language. ## Request trial or full license The Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps: 1. Contact the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license. If you already have a license key and you need to copy it, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). ## Get started with a sample project Learn how to use the Toolbox add-on using a C code example. The ImageExtraction example extracts all images and image masks from a PDF document. Use similar steps to run any other code example from the [toolbox-examples-c](https://github.com/pdf-tools/toolbox-examples-c) repository. ### Prerequisites This code example uses **GCC toolset 4.8+** and **CMake version 3.16** or higher. ### Compile and run the sample 1. Clone the **[toolbox-examples-c](https://github.com/pdf-tools/toolbox-examples-c)** repository: ```bash git clone https://github.com/pdf-tools/toolbox-examples-c.git ``` 1. Navigate to the `ImageExtraction` code example: ```bash cd toolbox-examples-c/ImageExtraction ``` 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. In the `toolboximageextraction.c` file, replace the `"insert-license-key-here"` placeholder in the `Ptx_Sdk_Initialize` call with your license key: ```c GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(Ptx_Sdk_Initialize(_T("insert-license-key-here"), NULL), _T("Failed to set license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, Ptx_GetLastError()); ``` Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. 1. Configure the project: ```shell cmake . ``` 1. Build the sample: ```shell cmake --build . ``` 1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/tmp/images`, run: ```shell ./toolboximageextraction ImageCollection.pdf /tmp/images ``` The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. Review this snippet with a placeholder and compare it to the last step of the previous procedure: ```shell ./toolboximageextraction INPUT_FILE OUTPUT_FILE ``` **note: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page.** ## Integrate the Toolbox add-on into your application Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections. ### Add the Toolbox add-on to your project 1. Click the **[download link](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/PdfTools_Toolbox_C-latest.zip)** to get the latest version of the Toolbox add-on for C in a zip archive. 1. Unzip the file on your machine into a local directory recommended for your operating system. For example: **Windows:** ``` C:\Program Files\PDF Tools AG\ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lib` | Runtime executable binaries and runtime import libraries: `win-x86\PdfTools_Toolbox.dll` and `win-x86\PdfTools_Toolbox.lib` for 32-bit Windows.`win-x64\PdfTools_Toolbox.dll` and `win-x64\PdfTools_Toolbox.lib` for 64-bit Windows.`win-arm64\PdfTools_Toolbox.dll` and `win-arm64\PdfTools_Toolbox.lib` for 64-bit Windows ARM. | | `include` | Header files to add to your C or C++ project. The main header `PdfTools_Toolbox.h` includes all the other headers. | **Linux:** ``` /opt/pdftools.com/ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | `lib` | Runtime executable binaries for all supported platforms: `linux-x64/libPdfToolsSdk.so` for 64-bit Linux`linux-arm64/libPdfToolsSdk.so` for 64-bit Linux ARM | | `include` | Header files to add to your C or C++ project. The main header `PdfTools_Toolbox.h` includes all the other headers. | **macOS:** ``` /opt/pdftools.com/ ``` Included subdirectories are: | Subdirectory | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lib` | Runtime executable binaries: `osx-x64/libPdfTools_Toolbox.dylib` for 64-bit (Intel) macOS `osx-arm64/libPdfTools_Toolbox.dylib` for ARM (Apple Silicon) macOS | | `include` | Header files to add to your C or C++ project. The main header PdfTools_Toolbox.h includes all the other headers. | 1. Optional: The native libraries must be available in your compiler's library path. This step is only required if your build process doesn't resolve it automatically: **Windows:** Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable. **Linux:** Create a link to the shared library from one of the standard library directories. For example: ``` ln -s /opt/pdf-tools.com/lib/linux-x64/libPdfTools_Toolbox.so /usr/lib ``` **macOS:** Create a link to the shared library from one of the standard library directories. For example (for an Intel processor Mac): ``` ln -s /opt/pdf-tools.com/lib/osx-x64/libPdfTools_Toolbox.dylib /usr/lib ``` ### Initialize the Toolbox add-on The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on function call fails with `LicenseError: No license key was set`. :::tip[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a trial or full license. To initialize the Toolbox add-on with your license key, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Ptx_Sdk_Initialize` once at application startup, before any other Toolbox add-on function call: ```c GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(Ptx_Sdk_Initialize(_T("YOUR_LICENSE_KEY"), NULL), _T("Failed to set license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff, Ptx_GetLastError()); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Ptx_Sdk_Initialize` function, follow these steps: 1. Clone the **[toolbox-examples-c](https://github.com/pdf-tools/toolbox-examples-c)** repository and navigate to a sample directory. For example, `toolbox-examples-c/ImageExtraction`. 1. Open the main C file and find the `Ptx_Sdk_Initialize` call. For example, the [ImageExtraction C sample](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ImageExtraction) includes it in `toolboximageextraction.c`. 1. Replace the `"insert-license-key-here"` placeholder with your license key. ### Uninitialize the Toolbox add-on After processing files with the Toolbox add-on, call `Ptx_Uninitialize` to unload the library correctly: ```c // Uninitialize library Ptx_Uninitialize(); ``` ### Implement your use case - Find more use cases and code examples on the Toolbox add-on [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page. - For more technical information about the Toolbox add-on for C, consult the [C technical notes](https://www.pdf-tools.com/docs/toolbox-add-on/api-references/technical-notes/c-notes). --- ## Get started with .NET(Getting-started) This guide walks you through the steps to use a code example, and then explains how to integrate the Toolbox add-on into your application with .NET. ## Request trial or full license The Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps: 1. Contact the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license. If you already have a license key and you need to copy it, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). ## Prerequisites The Toolbox add-on for .NET requires **.NET and .NET Core 2.0 or higher**, or **.NET Framework 4.6.1 or higher**. ## Get started with a sample project Learn how to use the Toolbox add-on using a C# code example. The ImageExtraction example extracts all images and image masks from a PDF document. Use similar steps to run any other code example from the [toolbox-examples-csharp](https://github.com/pdf-tools/toolbox-examples-csharp) repository. ### Compile and run the sample Switch between these tabs to display steps for the command line interface or for the Visual Studio. To compile and run the sample, follow these steps: **Command line:** 1. Clone the **[toolbox-examples-csharp](https://github.com/pdf-tools/toolbox-examples-csharp)** repository: ```bash git clone https://github.com/pdf-tools/toolbox-examples-csharp.git ``` 1. Navigate to the `ImageExtraction` code example: ```bash cd toolbox-examples-csharp/ImageExtraction ``` 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. In the `Program.cs` file, replace the `"insert-license-key-here"` placeholder in the `Sdk.Initialize` method call with your license key: ```csharp Sdk.Initialize("insert-license-key-here", null); ``` Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. 1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/tmp/images`, run the compiled sample application: ```shell dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj ImageCollection.pdf /tmp/images ``` The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. Review this snippet with a placeholder and compare it to the last step of the previous procedure: ```shell dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj INPUT_FILE OUTPUT_DIRECTORY ``` **Visual Studio:** **info: This documentation uses Visual Studio 2022.** 1. Clone the **[toolbox-examples-csharp](https://github.com/pdf-tools/toolbox-examples-csharp)** repository: ```bash git clone https://github.com/pdf-tools/toolbox-examples-csharp.git ``` 1. Open the project in Visual Studio: ``` toolbox-examples-csharp/ImageExtraction/ToolboxImageExtraction.csproj ``` 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. In the `Program.cs` file, replace the `"insert-license-key-here"` placeholder in the `Sdk.Initialize` method call with your license key: ```csharp Sdk.Initialize("insert-license-key-here", null); ``` Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. 1. Click **Build** -> **Build Solution** to compile the project. 1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/tmp/images`, run the compiled sample application: ```shell ToolboxImageExtraction ImageCollection.pdf /tmp/images ``` The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. Review this snippet with a placeholder and compare it to the last step of the previous procedure: ```shell ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY ``` **tip: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page.** ## Integrate the Toolbox add-on into your application Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections. ### Add the Toolbox add-on to your project **Command line:** In the project directory, add the package: ```shell dotnet add package PdfTools.Toolbox ``` Optional: If you want to use a specific version of the Toolbox add-on, specify the version: ```shell dotnet add package PdfTools.Toolbox --version ``` **Visual Studio:** **info: The integration section describes the process using Visual Studio 2022 on Windows. ** 1. Open your solution in Visual Studio. 1. Click **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution...**. 1. Click the **Search** tab and search for `PdfTools.Toolbox`. 1. Select the NuGet package named `PdfTools.Toolbox by PDF Tools AG`, select your Project, and then click **Install**. 1. Click **OK** to allow the changes, and then review and **Accept** the license agreement. ### Initialize the Toolbox add-on The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on method call fails with `LicenseError: No license key was set`. :::tip[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a trial or full license. To initialize the Toolbox add-on with your license key, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.Initialize` once at application startup, before any other Toolbox add-on method call: ```csharp Sdk.Initialize("YOUR_LICENSE_KEY", null); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.Initialize` method, follow these steps: 1. Clone the **[toolbox-examples-csharp](https://github.com/pdf-tools/toolbox-examples-csharp)** repository and navigate to a sample directory. For example, `toolbox-examples-csharp/ImageExtraction`. 1. Open `Program.cs` and find the `Sdk.Initialize` call. For example, the [ImageExtraction C# sample](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ImageExtraction) includes it in `Program.cs`. 1. Replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case - Find more use cases and code examples on the Toolbox add-on [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page. - For more technical information about the Toolbox add-on for .NET, consult the [.NET technical notes](https://www.pdf-tools.com/docs/toolbox-add-on/api-references/technical-notes/dotnet-notes). --- ## Get started with Java(Getting-started) This guide walks you through the steps to use a code example, and then explains how to integrate the Toolbox add-on into your application with the Java programming language. ## Request trial or full license The Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps: 1. Contact the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license. If you already have a license key and you need to copy it, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). ## Prerequisites The Toolbox add-on for Java requires **Java version 8 or higher**. ## Get started with a sample project Learn how to use the Toolbox add-on using a Java code example. The ImageExtraction example extracts all images and image masks from a PDF document. Use similar steps to run any other code example from the [toolbox-examples-java](https://github.com/pdf-tools/toolbox-examples-java) repository. ### Compile and run the sample Switch between the following tabs to display steps for the CLI (Maven or Gradle), Eclipse IDE, or IntelliJ IDEA. To compile and run the sample, follow these steps: 1. Clone the **[toolbox-examples-java](https://github.com/pdf-tools/toolbox-examples-java)** repository: ```bash git clone https://github.com/pdf-tools/toolbox-examples-java.git ``` 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Open `toolbox-examples-java/ImageExtraction/lib/src/main/java/ToolboxImageExtraction/ToolboxImageExtraction.java`, and replace the `"insert-license-key-here"` placeholder in the `Sdk.initialize` method call with your license key: ```java Sdk.initialize("insert-license-key-here", null); ``` Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. **CLI: Maven:** 1. Navigate to the `ImageExtraction` code example: ```bash cd toolbox-examples-java/ImageExtraction ``` 1. Create an output directory: ``` mkdir output_images ``` 1. Build and run the sample to extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `output_images`: ```bash mvn clean install mvn exec:java -Dexec.mainClass="ToolboxImageExtraction.ToolboxImageExtraction" -Dexec.args="ImageCollection.pdf output_images" ``` The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. Review this snippet with a placeholder and compare it to the last step of the previous procedure: ```bash mvn exec:java -Dexec.mainClass="ToolboxImageExtraction.ToolboxImageExtraction" -Dexec.args="INPUT_FILE OUTPUT_DIRECTORY" ``` **CLI: Gradle:** 1. Navigate to the `ImageExtraction` code example: ```bash cd toolbox-examples-java/ImageExtraction ``` 1. Create an output directory: ``` mkdir output_images ``` 1. Build and run the sample to extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `output_images`: ```bash ./gradlew run --args="ImageCollection.pdf output_images" ``` :::note - On Windows, use `gradlew` (or `gradlew.bat`) instead of `./gradlew`. - On macOS and Linux, you may need to make the wrapper executable first: `chmod +x gradlew` ::: The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. Review the following snippet with a placeholder and compare it to the last step of the previous procedure: ```bash ./gradlew run --args="INPUT_FILE OUTPUT_DIRECTORY" ``` **Eclipse IDE:** 1. Open Eclipse and navigate to **File** > **Import**. 1. Select **Maven** > **Existing Maven Projects** (or **Gradle** > **Existing Gradle Project**) and click **Next**. 1. Browse to `toolbox-examples-java/ImageExtraction` and click **Finish**. 1. In the **Package Explorer**, locate the main class containing the `main` method. 1. Right-click the file and select **Run As** > **Java Application**. **IntelliJ IDEA:** 1. Open IntelliJ IDEA and navigate to **File** > **Open**. 1. Select `toolbox-examples-java/ImageExtraction` and click **OK**. 1. When prompted, choose to import the project as a **Maven** or **Gradle** project. 1. In the **Project** tool window, locate the main class containing the `main` method. 1. Right-click the file and select **Run 'ToolboxImageExtraction'**. **note: You can apply a similar procedure described in this tutorial for other code examples. For more information, see [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page.** ## Integrate the Toolbox add-on into your application Integrate and initialize the Toolbox add-on into your application by following the instructions in these sections. ### Add the Toolbox add-on to your project To add the Toolbox add-on to your project, use one of the following methods: **Maven:** The Toolbox add-on for Java is available on Maven Central. To add the Toolbox add-on for Java to your project, add the following to your `pom.xml`: ```xml com.pdftools toolbox 1.12.1 ``` The dependency includes native binaries for all supported platforms, which are loaded automatically at runtime. **Gradle:** The Toolbox add-on for Java is available on Maven Central. To add the Toolbox add-on for Java to your project, add the following to your `build.gradle`: ```groovy implementation 'com.pdftools:toolbox:1.12.1' ``` The dependency includes native binaries for all supported platforms, which are loaded automatically at runtime. **Manual:** 1. Download [`toolbox-1.12.1.jar`](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.1/toolbox-1.12.1.jar) from Maven Central ([sources jar](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.1/toolbox-1.12.1-sources.jar), [javadoc jar](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.1/toolbox-1.12.1-javadoc.jar)). 1. Download [`toolbox-native-1.12.1.jar`](https://repo1.maven.org/maven2/com/pdftools/toolbox-native/1.12.1/toolbox-native-1.12.1.jar) from Maven Central (native libraries). 1. Add both JARs to your project's classpath. ### Initialize the Toolbox add-on The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on method call fails with `LicenseError: No license key was set`. :::tip[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a trial or full license. To initialize the Toolbox add-on with your license key, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.initialize` once at application startup, before any other Toolbox add-on method call: ```java Sdk.initialize("YOUR_LICENSE_KEY", null); ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.initialize` method, follow these steps: 1. Clone the **[toolbox-examples-java](https://github.com/pdf-tools/toolbox-examples-java)** repository and navigate to a sample directory. For example, `toolbox-examples-java/ImageExtraction`. 1. Open the main Java file and find the `Sdk.initialize` call. For example, the [ImageExtraction Java sample](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ImageExtraction) includes it in `lib/src/main/java/ToolboxImageExtraction/ToolboxImageExtraction.java`. 1. Replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case - Find more use cases and code examples on the [Code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page. - For more technical information about the Toolbox add-on for Java, consult the [Java technical notes](https://www.pdf-tools.com/docs/toolbox-add-on/api-references/technical-notes/java-notes). --- ## Get started with Python(Getting-started) This guide walks you through the steps to use the Toolbox add-on in a code example with Python. **info: The Python interface wraps the Toolbox add-on C API. For more details about specific functions and properties, review [C API reference](https://api-reference.pdf-tools.com/pdfsdkxt/1.1/cdoc/files.html) documentation.** ## Request trial or full license Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps: 1. Contact the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Toolbox add-on as the product of your interest for a trial license. If you already have a license key and you need to copy it, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). ## Prerequisites The Toolbox add-on for Python requires **Python 3.6 or higher**. ## Get started with a sample project Learn how to use the Toolbox add-on using a Python code example. The AddText example adds text to a PDF. Use similar steps to run any other code example from the [toolbox-examples-python](https://github.com/pdf-tools/toolbox-examples-python) repository. ### Clone and run the sample 1. Clone the **[toolbox-examples-python](https://github.com/pdf-tools/toolbox-examples-python)** repository: ```bash git clone https://github.com/pdf-tools/toolbox-examples-python.git ``` 1. Navigate to the `AddText` code example: ```bash cd toolbox-examples-python/AddText ``` 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. In the `add_text.py` file, replace the `"insert-license-key-here"` placeholder in the `Sdk.initialize` method call with your license key: ```python Sdk.initialize("insert-license-key-here", None) ``` Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. 1. Install the package for the Toolbox add-on by executing: ```bash pip install pdftools_toolbox ``` 1. To add the text string "Hello World!" to the first page of the PDF file `BlankNoneNoTP.pdf`, run: ```shell python ./add_text.py BlankNoneNoTP.pdf "Hello World!" output.pdf ``` :::note Run `python3` instead on systems where only Python 3 is installed and `python` is not aliased. ::: The code example takes: - The input and output files represented as a file name, a file path with the file name, or the output directory. - Both file paths (input and output) can be relative or absolute. - The text to be added to the output PDF, written between double quotation marks. Review this snippet with a placeholder and compare it to the last step of the previous procedure: ```bash python ./add_text.py INPUT_FILE "TEXT_TO_BE_ADDED" OUTPUT_FILE ``` ## Integrate the Toolbox add-on into your application Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections. ### Add the Toolbox add-on to your project To add the Toolbox add-on to your project, follow these steps: 1. Install the package for the Toolbox add-on by executing: ```shell pip install pdftools_toolbox ``` 1. Clone the **[toolbox-examples-python](https://github.com/pdf-tools/toolbox-examples-python)** repository and navigate to any sample directory. 1. Review the `README.md` file with usage details. Every code example includes a `README.md` with different usage instructions. 1. Import these packages in the header of your Python code: ```python from pdftools_toolbox.sdk import Sdk from pdftools_toolbox.geometry.real import Point from pdftools_toolbox.pdf import Document, FileReference, Metadata, PageCopyOptions, Page, PageList from pdftools_toolbox.pdf.content import Font, ContentGenerator, IccBasedColorSpace, Text, TextGenerator from pdftools_toolbox.pdf.navigation import ViewerSettings ``` :::info[Imports depend on the sample you use] The imports depend on the Python sample you use. Imports displayed in the last step of the previous procedure are valid for the [Add text to PDF](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddText) sample. Every sample includes a single Python file from which you can copy the imports. To use a different feature, copy the correct imports into your project: 1. In the **[toolbox-examples-python](https://github.com/pdf-tools/toolbox-examples-python)** repository, navigate to a sample directory. For example: `toolbox-examples-python/MultipleUp`. 1. Open the `multiple_up.py` file, and then copy its imports to the header of your Python code. ### Initialize the Toolbox add-on The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on method call fails with `LicenseError: No license key was set`. :::tip[Getting a license key] Contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a trial or full license. To initialize the Toolbox add-on with your license key, follow these steps: 1. Find your license key. For more information, review [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key). 1. Call `Sdk.initialize` once at application startup, before any other Toolbox add-on method call: ```python Sdk.initialize("YOUR_LICENSE_KEY", None) ``` Replace `YOUR_LICENSE_KEY` with your license key. Use the license key in the same format you copied it. Include the less-than (`<`) and greater-than (`>`) signs. To get a working reference with the `Sdk.initialize` method, follow these steps: 1. Clone the **[toolbox-examples-python](https://github.com/pdf-tools/toolbox-examples-python)** repository and navigate to a sample directory. For example, `toolbox-examples-python/AddText`. 1. Open the main Python file and find the `Sdk.initialize` call. For example, the [AddText Python sample](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddText) includes it in `add_text.py`. 1. Replace the `"insert-license-key-here"` placeholder with your license key. ### Implement your use case Find other code examples that show you how to implement specific use cases with the Toolbox add-on using Python. Review the [Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) page. --- ## Guides(3) # Toolbox add-on Guides Learn about various functionalities of the Toolbox add-on. --- ## A primer on PDF accessibility The primary goal of accessibility compliance is to ensure that individuals with disabilities can access and use information equally. This is achieved through measures that either directly assist the user or support the assistive technologies they use. ## Why accessibility matters for humans and machines A truly accessible PDF serves: - **Users**: An accessible PDF provides navigational aids like a clear structure, bookmarks, and proper reading order. The accessible PDF makes content legible through suitable contrast and colors and provides text alternatives for non-text content like images for screen readers. This helps not only users with permanent visual impairments but also those with temporary disabilities or anyone trying to read a document on a small mobile screen. - **Machines**: A well-tagged PDF becomes a machine-readable document, enabling robust data extraction, reliable text searching, and content re-use, where you can rearrange content to fit different screen sizes without losing its meaning or structure. ## Pillars of an accessible PDF Key components determine a PDF document’s accessibility: - **Searchable and selectable text**: The document must contain real text, not just images of text, so screen readers can access it and users can search it. - **Alternative text for images**: All meaningful images must have alternative text (`alt-text`) that describes their content or function. - **Logical structure and reading order**: You must tag the document with a hierarchical structure tree that defines the reading order and identifies elements like headings, paragraphs, lists, and tables. - **Navigational aids**: Bookmarks, a table of contents, and logical heading structures help users navigate the document efficiently. - **Contrast and visual design**: To improve readability, text must have enough contrast against its background. However, contrast should not be the only means of conveying information. - **Language specification**: To allow screen readers to use the correct pronunciation, specify the primary language and any language changes. The following standards and best practices define these accessibility requirements: - **[PDF/UA (ISO 14289)](https://www.iso.org/standard/64599.html)**: The international standard for accessible PDF documents. - **[WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/)**: Web Content Accessibility Guidelines applicable to PDFs. - **[Well-Tagged PDF](https://www.adobe.com/accessibility/pdf/pdf-accessibility-overview.html)**: Best practices for document structure. ## Human in the loop While this SDK handles the technical implementation, creating accessible PDF documents requires human understanding and judgment. Accessibility goes beyond technical compliance. Accessibility requires understanding how people actually use documents. - **Expertise**: Understanding the standards, formats, and workflows. - **Perspective**: Thinking from the user’s point of view. - **Tools**: Using software that handles the technical heavy lifting. - **Plain language**: Writing content that people with cognitive disabilities can understand. The accessibility software provided by Pdftools ensures technical compliance, but human oversight is essential to confirm that the document is genuinely usable and understandable. This includes using clear, simple language and avoiding jargon—principles of plain language that make documents accessible to people with cognitive disabilities, learning differences, or limited literacy skills. ## Accessibility guides Learn how to improve PDF accessibility using the Toolbox add-on SDK by following these guides: --- ## Add logical structure to an existing PDF Make PDF documents accessible by adding a logical structure using the Toolbox add-on. Learn about the technical process of PDF remediation, which means adding tags and structure to existing PDF content. If you work with a new PDF or have control over the document creation process, consider **[Create an accessible PDF from scratch](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/create-accessible-pdf)** instead. Creating accessible documents from scratch proves more efficient and reliable than remediation. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/TagPdf)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TagPdf)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TagPdf)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TagPdf)**. For background on PDF accessibility concepts and the importance of logical structure, review **[A primer on PDF accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/)**. Adding logical structure to an existing PDF involves analyzing the current content and selectively applying tags to create a hierarchical structure. **Steps to add logical structure to an existing PDF**: 1. [Open the existing document](#open-the-existing-document) 2. [Create the logical structure tree](#create-the-logical-structure-tree) 3. [Identify and copy content](#identify-and-copy-content) 4. [Tag specific content elements](#tag-specific-content-elements) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Toolbox add-on license](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/#initialize-the-toolbox-add-on-license)**. ## Open the existing document To begin, open the existing PDF and create a new output document. Since you work with existing content, copy the document-wide metadata before remediating individual pages. While the main work involves applying a logical structure to the PDF visual elements, specific metadata must conform to the PDF/Universal Accessibility (PDF/UA) standard. These requirements include setting a valid document language and a title. You must also configure the PDF to instruct viewers to display the document title in the title bar. Finally, once the entire PDF has been successfully tagged, you can declare it as PDF/UA compliant. This code shows the high-level process for opening the input document, creating the output document, copying document-wide data, and ensuring all required metadata fields have suitable values. **.NET:** ```csharp // Open input document using Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read); using Document inDoc = Document.Open(inStream, null); // Create output document using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite); using Document outDoc = Document.Create(outStream, inDoc.Conformance, null); CopyDocumentData(inDoc, outDoc); // Set required metadata for PDF/UA compliance outDoc.Language = "en"; outDoc.Metadata.Title = "TaggedPDF"; outDoc.ViewerSettings.DisplayDocumentTitle = true; // Remediating a PDF manually requires knowledge of the input PDF's layout. // This example assumes that the input is a single-page PDF. if (inDoc.Pages.Count != 1) throw new InvalidOperationException("Unexpected number of pages: " + inDoc.Pages.Count); RemediatePage(inDoc, 0, outDoc); outDoc.SetPdfUaConformant(); ``` **Java:** ```java try (FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStream, null); FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); Document outDoc = Document.create(outStream, inDoc.getConformance(), null)) { copyDocumentData(inDoc, outDoc); // Set required metadata for PDF/UA compliance outDoc.setLanguage("en"); outDoc.getMetadata().setTitle("TaggedPDF"); outDoc.getViewerSettings().setDisplayDocumentTitle(true); // Remediating a PDF manually requires knowledge of the input PDF's layout. // This example assumes that the input is a single-page PDF. if (inDoc.getPages().size() != 1) { throw new IllegalStateException("Unexpected number of pages: " + inDoc.getPages().size()); } remediatePage(inDoc, 0, outDoc); outDoc.setPdfUaConformant(); } ``` **Python:** ```python # Open input document with open(in_path, 'rb') as in_stream: with Document.open(in_stream, None) as in_doc: # Create output document with open(out_path, 'wb+') as out_stream: with Document.create(out_stream, in_doc.conformance, None) as out_doc: copy_document_data(in_doc, out_doc) # Set required metadata for PDF/UA compliance out_doc.language = "en" out_doc.metadata.title = "TaggedPDF" out_doc.viewer_settings.display_document_title = True # Remediating a PDF manually requires knowledge of the input PDF's layout. # This example assumes that the input is a single-page PDF. if len(in_doc.pages) != 1: raise ValueError(f"Unexpected number of pages: {len(in_doc.pages)}") remediate_page(in_doc, 0, out_doc) out_doc.set_pdf_ua_conformant() ``` ## Create the logical structure tree The RemediatePage method handles the page-level remediation process. It begins by creating a new, empty page in the output document that matches the dimensions of the original page. **.NET:** ```csharp private static void RemediatePage(Document inDoc, int pageIndex, Document outDoc) { Page inPage = inDoc.Pages[pageIndex]; Page outPage = Page.Create(outDoc, inPage.Size); CopyAndTagContent(inPage, outPage, outDoc); outDoc.Pages.Add(outPage); } ``` **Java:** ```java private static void remediatePage(Document inDoc, int pageIndex, Document outDoc) throws Exception { Page inPage = inDoc.getPages().get(pageIndex); Page outPage = Page.create(outDoc, inPage.getSize()); copyAndTagContent(inPage, outPage, outDoc); outDoc.getPages().add(outPage); } ``` **Python:** ```python def remediate_page(in_doc: Document, page_index: int, out_doc: Document): in_page = in_doc.pages[page_index] out_page = Page.create(out_doc, in_page.size) copy_and_tag_content(in_page, out_page, out_doc) out_doc.pages.append(out_page) ``` Instantiating a `Tree` object creates the logical structure on the first call and returns the existing tree on all later calls. The root node is always of type `DocumentNode`. For this example, the code wraps the entire page in a section node (`Sect`) to define the high-level logical structure. Next, a `ContentExtractor` retrieves content elements from the source page, and a `ContentGenerator` re-creates them on the destination page. The `for-loop` iterates through each element from the source page, identifies it, applies the correct tag, and then copies it to the destination. **.NET:** ```csharp private static void CopyAndTagContent(Page inPage, Page outPage, Document outDoc) { // Create or retrieve the structure tree. var structTree = new Tree(outDoc); var documentNode = structTree.DocumentNode; // Create a section node for the page content and add it to the document structure. var section = new Node("Sect", outDoc, outPage); documentNode.Children.Add(section); ContentExtractor extractor = new ContentExtractor(inPage.Content); using ContentGenerator generator = new ContentGenerator(outPage.Content, false); foreach (ContentElement element in extractor) { // The logic to identify, tag, and add the element to the generator goes here. // This process is detailed in the following examples // and is specific to the document's layout. // PDF/UA requires all content to be tagged. // Throw an exception for any unrecognized element to avoid untagged content. throw new InvalidOperationException("Unexpected content element found."); } } ``` **Java:** ```java private static void copyAndTagContent(Page inPage, Page outPage, Document outDoc) throws Exception { // Create or retrieve the structure tree. Tree structTree = new Tree(outDoc); Node documentNode = structTree.getDocumentNode(); // Create a section node for the page content and add it to the document structure. Node section = new Node("Sect", outDoc, outPage); documentNode.getChildren().add(section); ContentExtractor extractor = new ContentExtractor(inPage.getContent()); try (ContentGenerator generator = new ContentGenerator(outPage.getContent(), false)) { for (ContentElement element : extractor) { // The logic to identify, tag, and add the element to the generator goes here. // This process is detailed in the following examples // and is specific to the document's layout. // PDF/UA requires all content to be tagged. // Throw an exception for any unrecognized element to avoid untagged content. throw new IllegalStateException("Unexpected content element found."); } } } ``` **Python:** ```python def copy_and_tag_content(in_page: Page, out_page: Page, out_doc: Document): # Create or retrieve the structure tree. struct_tree = Tree(out_doc) document_node = struct_tree.document_node # Create a section node for the page content and add it to the document structure. section = Node("Sect", out_doc, out_page) document_node.children.append(section) extractor = ContentExtractor(in_page.content) with ContentGenerator(out_page.content, False) as generator: for element in extractor: # The logic to identify, tag, and add the element to the generator goes here. # This process is detailed in the following examples # and is specific to the document's layout. # PDF/UA requires all content to be tagged. # Throw an exception for any unrecognized element to avoid untagged content. raise ValueError("Unexpected content element found.") ``` ## Identify and copy content Identifying content elements to apply the correct tag requires specific knowledge of the document's layout. You can use specific properties for this identification. For instance, text elements have identifiable content, while non-textual elements like images have identifiable positions and sizes on the page (for example, by their bounding box). This code demonstrates these two approaches. This logic goes inside the for each loop shown earlier. **.NET:** ```csharp if (element is TextElement textElement) { if (textElement.Text[0].Text == "This is a properly tagged heading") { CopyAndTagTextElement(textElement, section, generator, outPage, outDoc, "H1"); continue; } if (textElement.Text[0].Text.StartsWith("This is a properly tagged paragraph.")) { CopyAndTagTextElement(textElement, section, generator, outPage, outDoc, "P"); continue; } // Add more logic here to identify other text elements. } else if (element is ImageElement imageElement) { var bbox = imageElement.Transform.TransformRectangle(element.BoundingBox); if (Math.Abs(bbox.BottomLeft.X - 56.7) < 0.5 && Math.Abs(bbox.BottomLeft.Y - 600.489) < 0.5 && Math.Abs(bbox.TopRight.X - 152.489) < 0.5 && Math.Abs(bbox.TopRight.Y - 696.489) < 0.5) { CopyAndTagImageElement(imageElement, documentNode, generator, outPage, outDoc, "PdfTools AG Logo"); continue; } // Add more logic here to identify other image elements. } // Remember, if an element is not identified by the logic above, the surrounding // code will throw an exception to ensure all content is tagged. ``` **Java:** ```java if (element instanceof TextElement) { TextElement textElement = (TextElement) element; if (textElement.getText().get(0).getText().equals("This is a properly tagged heading")) { copyAndTagTextElement(textElement, section, generator, outPage, outDoc, "H1"); continue; } if (textElement.getText().get(0).getText().startsWith("This is a properly tagged paragraph.")) { copyAndTagTextElement(textElement, section, generator, outPage, outDoc, "P"); continue; } // Add more logic here to identify other text elements. } else if (element instanceof ImageElement) { ImageElement imageElement = (ImageElement) element; Quadrilateral bbox = imageElement.getTransform().transformRectangle(element.getBoundingBox()); if (Math.abs(bbox.getBottomLeft().getX() - 56.7) < 0.5 && Math.abs(bbox.getBottomLeft().getY() - 600.489) < 0.5 && Math.abs(bbox.getTopRight().getX() - 152.489) < 0.5 && Math.abs(bbox.getTopRight().getY() - 696.489) < 0.5) { copyAndTagImageElement(imageElement, documentNode, generator, outPage, outDoc, "PdfTools AG Logo"); continue; } // Add more logic here to identify other image elements. } // Remember, if an element is not identified by the logic above, the surrounding // code will throw an exception to ensure all content is tagged. ``` **Python:** ```python if isinstance(element, TextElement): if element.text[0].text == "This is a properly tagged heading": copy_and_tag_text_element(element, section, generator, out_page, out_doc, "H1") continue if element.text[0].text.startswith("This is a properly tagged paragraph."): copy_and_tag_text_element(element, section, generator, out_page, out_doc, "P") continue # Add more logic here to identify other text elements. elif isinstance(element, ImageElement): bbox = element.transform.transform_rectangle(element.bounding_box) if (abs(bbox.bottom_left.x - 56.7) < 0.5 and abs(bbox.bottom_left.y - 600.489) < 0.5 and abs(bbox.top_right.x - 152.489) < 0.5 and abs(bbox.top_right.y - 696.489) < 0.5): copy_and_tag_image_element(element, document_node, generator, out_page, out_doc, "PdfTools AG Logo") continue # Add more logic here to identify other image elements. # Remember, if an element is not identified by the logic above, the surrounding # code will throw an exception to ensure all content is tagged. ``` ## Tag specific content elements The key to successful remediation involves identifying which content elements need structure tags and applying the suitable tags. The following examples show how to handle different types of content: ### Tag text elements When tagging text, the main goal involves assigning the correct semantic role, such as a heading `H1`, a paragraph `P`, or a list item `LI`. Providing `ActualText` is also crucial for ensuring that screen readers and other assistive technologies can accurately interpret the content. **.NET:** ```csharp private static void CopyAndTagTextElement( TextElement inElement, Node section, ContentGenerator generator, Page outPage, Document outDoc, string tag) { // Create a text structure node (e.g., "H1"), set its ActualText // for accessibility, and add it to the parent section. Node headerElement = new Node(tag, outDoc, outPage); headerElement.ActualText = inElement.Text[0].Text; headerElement.Language = "en"; section.Children.Add(headerElement); // Wrap the original text element in the new tag and add it to the page content. generator.TagAs(headerElement); generator.AppendContentElement(ContentElement.Copy(outDoc, inElement)); generator.StopTagging(); } ``` **Java:** ```java private static void copyAndTagTextElement( TextElement inElement, Node section, ContentGenerator generator, Page outPage, Document outDoc, String tag) throws Exception { // Create a text structure node (e.g., "H1"), set its ActualText // for accessibility, and add it to the parent section. Node headerElement = new Node(tag, outDoc, outPage); headerElement.setActualText(inElement.getText().get(0).getText()); headerElement.setLanguage("en"); section.getChildren().add(headerElement); // Wrap the original text element in the new tag and add it to the page content. generator.tagAs(headerElement); generator.appendContentElement(ContentElement.copy(outDoc, inElement)); generator.stopTagging(); } ``` **Python:** ```python def copy_and_tag_text_element( in_element: TextElement, section: Node, generator: ContentGenerator, out_page: Page, out_doc: Document, tag: str ): # Create a text structure node (e.g., "H1"), set its ActualText # for accessibility, and add it to the parent section. header_element = Node(tag, out_doc, out_page) header_element.actual_text = in_element.text[0].text header_element.language = "en" section.children.append(header_element) # Wrap the original text element in the new tag and add it to the page content. generator.tag_as(header_element) generator.append_content_element(ContentElement.copy(out_doc, in_element)) generator.stop_tagging() ``` ### Tag image elements For images, the most important accessibility feature involves providing descriptive alternate text. Screen readers read this text aloud for users who can't see the image. Images typically are tagged as `Figure` elements, and you need to define their bounding box to associate the tag with the correct location on the page. **.NET:** ```csharp private static void CopyAndTagImageElement( ImageElement inElement, Node documentNode, ContentGenerator generator, Page outPage, Document outDoc, string alternateText) { // Create a "Figure" structure node, set its accessibility properties // (Alternate Text, Bounding Box), and add it to the document's structure tree. Node imgNode = new Node("Figure", outDoc, outPage); imgNode.AlternateText = alternateText; imgNode.Language = "en"; Quadrilateral bbox = inElement.Transform.TransformRectangle(inElement.BoundingBox); Rectangle rectangle = new Rectangle(); rectangle.Left = bbox.BottomLeft.X; rectangle.Bottom = bbox.BottomLeft.Y; rectangle.Right = bbox.TopRight.X; rectangle.Top = bbox.TopRight.Y; imgNode.BoundingBox = rectangle; imgNode.SetStringAttribute("O", "Layout"); documentNode.Children.Add(imgNode); // Wrap the original image element in the new tag and add it to the page content. generator.TagAs(imgNode); generator.AppendContentElement(ContentElement.Copy(outDoc, inElement)); generator.StopTagging(); } ``` **Java:** ```java private static void copyAndTagImageElement( ImageElement inElement, Node documentNode, ContentGenerator generator, Page outPage, Document outDoc, String alternateText) throws Exception { // Create a "Figure" structure node, set its accessibility properties // (Alternate Text, Bounding Box), and add it to the document's structure tree. Node imgNode = new Node("Figure", outDoc, outPage); imgNode.setAlternateText(alternateText); imgNode.setLanguage("en"); Quadrilateral bbox = inElement.getTransform().transformRectangle(inElement.getBoundingBox()); Rectangle rectangle = new Rectangle(); rectangle.setLeft(bbox.getBottomLeft().getX()); rectangle.setBottom(bbox.getBottomLeft().getY()); rectangle.setRight(bbox.getTopRight().getX()); rectangle.setTop(bbox.getTopRight().getY()); imgNode.setBoundingBox(rectangle); imgNode.setStringAttribute("O", "Layout"); documentNode.getChildren().add(imgNode); // Wrap the original image element in the new tag and add it to the page content. generator.tagAs(imgNode); generator.appendContentElement(ContentElement.copy(outDoc, inElement)); generator.stopTagging(); } ``` **Python:** ```python def copy_and_tag_image_element( in_element: ImageElement, document_node: Node, generator: ContentGenerator, out_page: Page, out_doc: Document, alternate_text: str ): # Create a "Figure" structure node, set its accessibility properties # (Alternate Text, Bounding Box), and add it to the document's structure tree. img_node = Node("Figure", out_doc, out_page) img_node.alternate_text = alternate_text img_node.language = "en" bbox = in_element.transform.transform_rectangle(in_element.bounding_box) rectangle = Rectangle( left=bbox.bottom_left.x, bottom=bbox.bottom_left.y, right=bbox.top_right.x, top=bbox.top_right.y ) img_node.bounding_box = rectangle img_node.set_string_attribute("O", "Layout") document_node.children.append(img_node) # Wrap the original image element in the new tag and add it to the page content. generator.tag_as(img_node) generator.append_content_element(ContentElement.copy(out_doc, in_element)) generator.stop_tagging() ``` ## Best practices for remediation When adding logical structure to existing PDF documents, consider these best practices: - **Content analysis**: Use heuristics to identify content types, but always validate results manually. Automated detection of headings, paragraphs, and other elements has inherent limitations. - **Quality assurance**: Always validate the remediated PDF with accessibility checkers and screen readers to make sure the logical structure works as intended. - **Alternative text**: Meaningful alternative text for images can't be automated. Always perform a human review before claiming PDF/UA compliance. ## Full example Get the complete remediation example on GitHub: - [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TagPdf) - [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TagPdf) - [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TagPdf) ## Next steps After adding logical structure to your PDF: - **Validate the structure:** Use PDF accessibility checkers to verify the logical structure. - **Test with assistive technology:** Ensure screen readers can navigate the document correctly. - **Review alternative text:** Manually verify that all images have meaningful descriptions. - **Check reading order:** Confirm the logical structure follows the intended reading flow. Adding logical structure to existing PDF documents requires technical skill, but true accessibility requires human understanding and validation. Always perform manual testing to make sure the remediated document serves its intended users effectively. --- ## Create an accessible PDF from scratch Using the Toolbox add-on, create fully accessible, tagged PDF documents from scratch. This guide walks you through the technical steps to create a valid PDF/UA document. A properly structured PDF is crucial not only for users with disabilities who rely on assistive technologies but also improves the experience for all users by enabling features like content reflow on mobile devices and improving machine-readability. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/CreateTaggedPdf)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/CreateTaggedPdf)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/CreateTaggedPdf)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/CreateTaggedPdf)**. For background on PDF accessibility concepts and the importance of logical structure, review **[A primer on PDF accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/)**. The process involves creating a document, defining its logical structure, and then adding content elements that are linked to that structure. **Steps to create a tagged PDF document**: 1. [Create the document and structure tree](#1-create-the-document-and-structure-tree) 1. [Add and tag content](#2-add-and-tag-content) 1. [Set accessibility metadata](#3-set-accessibility-metadata) --- :::note[Before you begin] You need to **[Initialize the Toolbox add-on license](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/#initialize-the-toolbox-add-on-license)**. ### 1. Create the document and structure tree You always start with an empty output `Document`. **.NET:** ```csharp // Create a PDF document using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite); using Document outDoc = Document.Create(outStream, null, null); // Create a font Font font = CreateFontWithFallbacks(outDoc, ARIAL_AND_FALLBACKS); // Create a page Size pageSize = new Size { Width = ToPoints(21, "cm"), Height = ToPoints(29.7, "cm") }; // DIN A4 Page outPage = Page.Create(outDoc, pageSize); // Generate the page's content CreateAndTagContent(outDoc, outPage, imagePath, font); outDoc.Pages.Add(outPage); ``` **Java:** ```java // Create a PDF document try (FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW); Document outDoc = Document.create(outStream, Conformance.PDF17, null)) { // Create a font Font font = createFontWithFallbacks(outDoc, ARIAL_AND_FALLBACKS); // Create a page Size pageSize = new Size(toPoints(21, "cm"), toPoints(29.7, "cm")); // DIN A4 Page outPage = Page.create(outDoc, pageSize); // Generate the page's content createAndTagContent(outDoc, outPage, imagePath, font); outDoc.getPages().add(outPage); ``` **Python:** ```python # Create a PDF document with io.FileIO(output_path, "wb+") as out_stream: with Document.create(out_stream, Conformance.PDF17, None) as out_doc: # Create a font font = create_font_with_fallbacks(out_doc, ARIAL_AND_FALLBACKS) # Create a page page_size = Size(to_points(21, "cm"), to_points(29.7, "cm")) # DIN A4 out_page = Page.create(out_doc, page_size) # Generate the page's content create_and_tag_content(out_doc, out_page, image_path, font) out_doc.pages.append(out_page) ``` :::note[Helper functions and constants] Helper functions like `createFontWithFallbacks` or `toPoints` and constants like `ARIAL_AND_FALLBACKS` can be viewed in the full example. The first step is to establish the logical structure tree. This is essential because content can only be tagged if a structure node already exists for it to reference. The structure tree begins with a `Tree` object, whose root is the `DocumentNode`. All other structure elements, like sections (`Sect`) and paragraphs (`P`), become children of this root. **.NET:** ```csharp private static void CreateAndTagContent(Document outputDoc, Page outPage, string imagePath, Font font) { using (ContentGenerator gen = new ContentGenerator(outPage.Content, false)) { // Create an empty logical structure tree and add a section to the root node (DocumentNode) Tree structTree = new Tree(outputDoc); Node docNode = structTree.DocumentNode; Node sectionNode = new Node("Sect", outputDoc, outPage); docNode.Children.Add(sectionNode); // Start from the top of the page with margin double currentY = outPage.Size.Height - MARGIN; // Create header currentY = CreateAndTagText( outputDoc, outPage, gen, sectionNode, font, currentY, "H1", "This is a properly tagged heading", 24.0); // Add padding and create paragraph currentY -= PADDING; currentY = CreateAndTagText( outputDoc, outPage, gen, sectionNode, font, currentY, "P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0); // Add padding and create image currentY -= PADDING; CreateAndTagImage(outputDoc, outPage, gen, imagePath, currentY); } } ``` **Java:** ```java private static void createAndTagContent(Document outDoc, Page outPage, String imagePath, Font font) throws Exception { try (ContentGenerator gen = new ContentGenerator(outPage.getContent(), false)) { // Create an empty logical structure tree and add a section to the root node (DocumentNode) Tree structTree = new Tree(outDoc); Node docNode = structTree.getDocumentNode(); Node sectionNode = new Node("Sect", outDoc, outPage); docNode.getChildren().add(sectionNode); // Start from the top of the page with margin double currentY = outPage.getSize().getHeight() - MARGIN; // Create header currentY = createAndTagText( outDoc, outPage, gen, sectionNode, font, currentY, "H1", "This is a properly tagged heading", 24.0); // Add padding and create paragraph currentY -= PADDING; currentY = createAndTagText( outDoc, outPage, gen, sectionNode, font, currentY, "P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0); // Add padding and create image currentY -= PADDING; createAndTagImage(outDoc, outPage, gen, imagePath, currentY); } } ``` **Python:** ```python def create_and_tag_content(out_doc: Document, out_page: Page, image_path: str, font: Font): with ContentGenerator(out_page.content, False) as gen: # Create an empty logical structure tree and add a section to the root node (DocumentNode) struct_tree = Tree(out_doc) doc_node = struct_tree.document_node section_node = Node("Sect", out_doc, out_page) doc_node.children.append(section_node) # Start from the top of the page with margin current_y = out_page.size.height - MARGIN # Create header current_y = create_and_tag_text( out_doc, out_page, gen, section_node, font, current_y, "H1", "This is a properly tagged heading", 24.0) # Add padding and create paragraph current_y -= PADDING current_y = create_and_tag_text( out_doc, out_page, gen, section_node, font, current_y, "P", "This is a properly tagged paragraph. Both heading and paragraph belong to a section.", 12.0) # Add padding and create image current_y -= PADDING create_and_tag_image(out_doc, out_page, gen, image_path, current_y) ``` ### 2\. Add and tag content With the structure tree in place, you can create page content and associate it with a specific structure node. This is done using a `ContentGenerator` and its `TagAs` method. The workflow is: 1. Start tagging by calling `gen.TagAs(node)`. 2. Add the content (for example, paint text or an image). 3. Stop tagging with `gen.StopTagging()`. #### 2\.1. Tag text When tagging text elements like headings or paragraphs, the `ActualText` property of the `Node` should be set. This provides an explicit text equivalent for screen readers. **.NET:** ```csharp private static double CreateAndTagText( Document outputDoc, Page outPage, ContentGenerator gen, Node sectionNode, Font font, double topY, string tagName, string textContent, double fontSize) { // Create a node in the logical structure tree // that will contain the text and add it to the section Node textNode = new Node(tagName, outputDoc, outPage); textNode.ActualText = textContent; sectionNode.Children.Add(textNode); // Calculate text baseline position double baselineY = topY - fontSize * font.Ascent; // From here on, all painted graphics will be contained within that node gen.TagAs(textNode); // Paint text onto the page Text text = Text.Create(outputDoc); using (TextGenerator textGen = new TextGenerator(text, font, fontSize, null)) { Point position = new Point { X = MARGIN, Y = baselineY }; textGen.MoveTo(position); textGen.ShowLine(textNode.ActualText); } gen.PaintText(text); gen.StopTagging(); // Return bottom coordinate (baseline - descent) return baselineY - fontSize * font.Descent; } ``` **Java:** ```java private static double createAndTagText( Document outDoc, Page outPage, ContentGenerator gen, Node sectionNode, Font font, double topY, String tagName, String textContent, double fontSize) throws Exception { // Create a node in the logical structure tree // that will contain the text and add it to the section Node textNode = new Node(tagName, outDoc, outPage); textNode.setActualText(textContent); sectionNode.getChildren().add(textNode); // Calculate text baseline position double baselineY = topY - fontSize * font.getAscent(); // From here on, all painted graphics will be contained within that node gen.tagAs(textNode); // Paint text onto the page Text text = Text.create(outDoc); try (TextGenerator textGen = new TextGenerator(text, font, fontSize, null)) { Point position = new Point(MARGIN, baselineY); textGen.moveTo(position); textGen.showLine(textNode.getActualText()); } gen.paintText(text); gen.stopTagging(); // Return bottom coordinate (baseline - descent) return baselineY - fontSize * font.getDescent(); } ``` **Python:** ```python def create_and_tag_text( out_doc: Document, out_page: Page, gen: ContentGenerator, section_node: Node, font: Font, top_y: float, tag_name: str, text_content: str, font_size: float) -> float: # Create a node in the logical structure tree # that will contain the text and add it to the section text_node = Node(tag_name, out_doc, out_page) text_node.actual_text = text_content section_node.children.append(text_node) # Calculate text baseline position baseline_y = top_y - font_size * font.ascent # From here on, all painted graphics will be contained within that node gen.tag_as(text_node) # Paint text onto the page text = Text.create(out_doc) with TextGenerator(text, font, font_size, None) as text_gen: position = Point(MARGIN, baseline_y) text_gen.move_to(position) text_gen.show_line(text_node.actual_text) gen.paint_text(text) gen.stop_tagging() # Return bottom coordinate (baseline - descent) return baseline_y - font_size * font.descent ``` #### 2\.2. Tag an image For non-text content, providing a text alternative is critical. For images (`Figure` nodes), you must set the `AlternateText` property. **.NET:** ```csharp private static double CreateAndTagImage( Document outputDoc, Page outPage, ContentGenerator gen, string imagePath, double topY) { // If a structure tree has already been created for the given document, // the existing structure tree reference will be returned. Tree tree = new Tree(outputDoc); Node docNode = tree.DocumentNode; Node figureNode = new Node("Figure", outputDoc, outPage); figureNode.AlternateText = "PdfTools AG Logo"; docNode.Children.Add(figureNode); // From here on, all painted graphics will be contained within that node gen.TagAs(figureNode); // Load an image Image image; using (Stream inImage = new FileStream(imagePath, FileMode.Open, FileAccess.Read)) { image = Image.Create(outputDoc, inImage); } // Paint the image onto the page double x = MARGIN; double width = ToPoints(2.0, "cm"); double height = width * image.Size.Height / image.Size.Width; // preserve aspect ratio Rectangle rect = new Rectangle { Left = x, // left Bottom = topY - height, // bottom (Rectangle coordinates: bottom is lower than top) Right = x + width, // right Top = topY // top }; gen.PaintImage(image, rect); gen.StopTagging(); // Return bottom coordinate return topY - height; } ``` **Java:** ```java private static double createAndTagImage( Document outDoc, Page outPage, ContentGenerator gen, String imagePath, double topY) throws Exception { // If a structure tree has already been created for the given document, // the existing structure tree reference will be used. Tree tree = new Tree(outDoc); Node docNode = tree.getDocumentNode(); Node figureNode = new Node("Figure", outDoc, outPage); figureNode.setAlternateText("PdfTools AG Logo"); docNode.getChildren().add(figureNode); // From here on, all painted graphics will be contained within that node gen.tagAs(figureNode); // Load an image Image image; try (FileStream inImage = new FileStream(imagePath, FileStream.Mode.READ_ONLY)) { image = Image.create(outDoc, inImage); } // Paint the image onto the page double x = MARGIN; double width = toPoints(2.0, "cm"); double height = width * image.getSize().getHeight() / image.getSize().getWidth(); // preserve aspect ratio Rectangle rect = new Rectangle( x, // left topY - height, // bottom (Rectangle coordinates: bottom is lower than top) x + width, // right topY // top ); gen.paintImage(image, rect); gen.stopTagging(); // Return bottom coordinate return topY - height; } ``` **Python:** ```python def create_and_tag_image( out_doc: Document, out_page: Page, gen: ContentGenerator, image_path: str, top_y: float) -> float: # If a structure tree has already been created for the given document, # the existing structure tree reference will be used. tree = Tree(out_doc) doc_node = tree.document_node figure_node = Node("Figure", out_doc, out_page) figure_node.alternate_text = "PdfTools AG Logo" doc_node.children.append(figure_node) # From here on, all painted graphics will be contained within that node gen.tag_as(figure_node) # Load an image with io.FileIO(image_path, "rb") as in_image: image = Image.create(out_doc, in_image) # Paint the image onto the page x = MARGIN width = to_points(2.0, "cm") height = width * image.size.height / image.size.width # preserve aspect ratio rect = Rectangle( left=x, bottom=top_y - height, # Rectangle coordinates: bottom is lower than top right=x + width, top=top_y, ) gen.paint_image(image, rect) gen.stop_tagging() # Return bottom coordinate return top_y - height ``` When writing alternative text, follow these best practices: - Be descriptive but concise - Convey the purpose of the image, not just its appearance - Don't start with "Image of..." or "Picture of..." - For complex diagrams, consider providing a longer description elsewhere ### 3\. Set accessibility metadata The SDK automatically sets the `Tagged` flag when you create a PDF's logical structure. However, you must explicitly set the PDF/UA flag when you're confident your document meets all accessibility requirements: **.NET:** ```csharp // Set document metadata outDoc.Metadata.Title = "Accessible Document Example"; outDoc.Metadata.Author = "Your Organization"; // Set language for the entire document outDoc.Language = "en-US"; // Only set PDF/UA flag after ensuring full accessibility compliance // This requires human verification beyond technical implementation // outDoc.SetPdfUaConformant(); // Uncomment only after full review ``` **Java:** ```java // Set document metadata outDoc.getMetadata().setTitle("Accessible Document Example"); outDoc.getMetadata().setAuthor("Your Organization"); // Set language for the entire document outDoc.setLanguage("en-US"); // Only set PDF/UA flag after ensuring full accessibility compliance // This requires human verification beyond technical implementation // outDoc.setPdfUaConformant(); // Uncomment only after full review ``` **Python:** ```python # Set document metadata out_doc.metadata.title = "Accessible Document Example" out_doc.metadata.author = "Your Organization" # Set language for the entire document out_doc.language = "en-US" # Only set PDF/UA flag after ensuring full accessibility compliance # This requires human verification beyond technical implementation # out_doc.set_pdf_ua_conformant() # Uncomment only after full review ``` :::warning[PDF/UA compliance] Setting the PDF/UA flag indicates that your document fully complies with the PDF/UA standard. This goes beyond technical structure and includes: - Proper color contrast ratios - Meaningful reading order - Appropriate use of headings - Complete alternative descriptions - Correct language specifications Always perform human review before claiming PDF/UA compliance. ## Full example Get the full example on GitHub to see all the pieces working together. - [C\#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/CreateTaggedPdf) - [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/CreateTaggedPdf) - [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/CreateTaggedPdf) ## Next steps After creating accessible PDFs: - **Validate accessibility:** Use PDF accessibility checkers to verify your implementation - **Test with assistive technology:** Try your PDFs with screen readers like NVDA or JAWS - **Learn about remediation:** See the guide on adding structure to existing PDFs - **Explore structure reading:** Learn how to read and analyze logical structure Creating truly accessible PDFs requires both technical implementation and human understanding. While the SDK provides the tools, achieving genuine accessibility requires thoughtful consideration of how people will use your documents. --- ## Read PDF logical structure Use the Toolbox add-on to read and traverse the logical structure of a tagged PDF document. This guide covers the technical process of accessing and analyzing existing document structure. If you need to add logical structure to an existing PDF, see the guide on **[Add logical structure to an existing PDF](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/add-logical-structure-to-existing-pdf)**. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/TraverseDocumentStructure)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TraverseDocumentStructure)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TraverseDocumentStructure)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TraverseDocumentStructure)**. For background on PDF accessibility concepts and the importance of logical structure, review **[A primer on PDF accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/)**. Reading logical structure involves accessing and traversing the document's structure tree to extract information about tagged elements. **Steps to read PDF logical structure**: 1. [Open the tagged document](#open-the-tagged-document) 2. [Access the structure tree](#access-the-structure-tree) 3. [Traverse the tree recursively](#traverse-the-tree-recursively) 4. [Read node properties](#read-node-properties) 5. [Full example](#full-example) --- :::note[Before you begin] You need to **[Initialize the Toolbox add-on license](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/#initialize-the-toolbox-add-on-license)**. ## Open the tagged document Start by opening the PDF document that contains a logical structure. Only tagged PDFs include accessible structure information. You can then check whether the PDF claims to be PDF/UA conformant using the is_pdf_ua_conformant property. **.NET:** ```csharp // Open input document using Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read); using Document inDoc = Document.Open(inStream, null); if (inDoc.IsPdfUaConformant) { Console.WriteLine("This PDF declares PDF/UA conformance."); } else { Console.WriteLine("This PDF does not declare PDF/UA conformance."); } ``` **Java:** ```java // Open input document try (FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStream, null)) { if (inDoc.getIsPdfUaConformant()) { System.out.println("This PDF declares PDF/UA conformance."); } else { System.out.println("This PDF does not declare PDF/UA conformance."); } ``` **Python:** ```python # Open input document with open(input_file_path, "rb") as in_stream: with Document.open(in_stream, None) as in_doc: if in_doc.is_pdf_ua_conformant: print("This PDF declares PDF/UA conformance.") else: print("This PDF does not declare PDF/UA conformance.") ``` :::warning[PDF/UA Declaration] The `isPdfUaConformant` flag only reflects the PDF's metadata declaration. It does **not** guarantee actual PDF/UA compliance — use a validator to verify true conformance. ## Access the structure tree Create a `Tree` object to access the document's logical structure. The tree provides access to the root document node and its children. **.NET:** ```csharp // Create a structure tree object var tree = new Tree(inDoc); // Traverse all top-level structure elements foreach (var child in tree.Children) { PrintNodeRecursively(child); } ``` **Java:** ```java // Create a structure tree object Tree tree = new Tree(inDoc); // Traverse all top-level structure elements for (Node node : tree.getChildren()) { printNodeRecursively(node, 0); } ``` **Python:** ```python # Create structure tree object tree = Tree(in_doc) # Traverse all top-level structure elements for node in tree.children: print_node_recursive(node, 0) ``` ## Traverse the tree recursively Implement a recursive function to traverse the entire structure tree. Each node can have child nodes, creating a hierarchical structure. **.NET:** ```csharp static void PrintNodeRecursively(Node node, int level = 0) { // Print current node information PrintProperty(level, "Tag", node.Tag); PrintProperty(level, "Alternative text", node.AlternateText); PrintProperty(level, "Actual text", node.ActualText); PrintProperty(level, "Language", node.Language); // Recursively traverse child nodes foreach (var child in node.Children) { PrintNodeRecursively(child, level + 1); } } ``` **Java:** ```java static void printNodeRecursively(Node node, int level) throws Exception { // Print current node information printProperty(level, "Tag", node.getTag()); printProperty(level, "Alternative text", node.getAlternateText()); printProperty(level, "Actual text", node.getActualText()); printProperty(level, "Language", node.getLanguage()); // Recursively traverse child nodes for (Node child : node.getChildren()) { printNodeRecursively(child, level + 1); } } ``` **Python:** ```python def print_node_recursive(node: Node, level: int): # Print current node information print_property(level, "Tag", node.tag) print_property(level, "Alternative text", node.alternate_text) print_property(level, "Actual text", node.actual_text) print_property(level, "Language", node.language) # Recursively traverse child nodes for child in node.children: print_node_recursive(child, level + 1) ``` ## Read node properties Each structure node contains various properties that provide information about the tagged element: - **Tag**: The structure type (for example, "H1", "P", "Figure", "Table") - **Actual Text**: The text content for text elements - **Alternative Text**: Alternative text for images and non-text elements - **Language**: Language specification for the element - **Abbreviation**: Expanded form of abbreviations **.NET:** ```csharp static void PrintProperty(int level, String name, String value) { Console.Write($"{new string(' ', level * 2)}"); Console.WriteLine($"{name}: '{value}'"); } ``` **Java:** ```java static void printProperty(int level, String name, String value) { for (int i = 0; i < level; ++i) { System.out.print(" "); } System.out.println(name + ": '" + value + "'"); } ``` **Python:** ```python def print_property(level: int, label: str, value): indent = " " * level value_str = str(value or "") print(f"{indent}{label}: '{value_str}'") ``` ## Example output When you run the structure traversal, the output is similar to this example: ``` This PDF declares PDF/UA conformance. Tag: 'Document' Alternative text: '' Actual text: '' Language: '' Tag: 'Title' Alternative text: '' Actual text: '' Language: '' Tag: 'Text body' Alternative text: '' Actual text: '' Language: '' Tag: 'Text body' Alternative text: '' Actual text: '' Language: '' Tag: 'Figure' Alternative text: 'A test image of a document icon' Actual text: '' Language: '' ``` ## Full example Get the complete structure traversal example on GitHub: - [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TraverseDocumentStructure) - [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TraverseDocumentStructure) - [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TraverseDocumentStructure) ## Use cases Reading logical structure is useful for: - **Accessibility auditing**: Verify that documents have proper structure - **Content extraction**: Extract structured content while preserving hierarchy - **Document analysis**: Understand document organization and reading order - **Quality assurance**: Validate that remediation or creation processes worked correctly Reading logical structure provides insights into how assistive technologies will interpret your PDF documents, making it an essential tool for accessibility validation. --- ## Add and fill form fields The Toolbox add-on lets you add and fill form fields in PDF documents. ## Form fields Form fields are placeholders for input data in a PDF document. An example of such input data might be a name, a date, or a choice from a group of items. The input data contained in a form field may be modified, if allowed, by the user who is viewing the PDF document. The Toolbox add-on supports the following types of form fields: - `General text` - `Comb text` - `Check box` - `Radio button` - `Combo box` - `List box` The special type `SubForm` can also be used to create logical groups of form fields. ## Add form fields Learn how to add form fields to a PDF document using the Add Form Field ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddFormFields), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddFormFields), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddFormFields), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddFormFields)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddFormFields)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddFormFields)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddFormFields)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddFormFields)**. ## Fill form fields Fill form fields in a PDF document using the Fill Form Fields ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FillFormFields), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FillFormFields), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FillFormFields), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FillFormFields)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FillFormFields)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FillFormFields)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FillFormFields)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FillFormFields)**. --- ## Manage annotations Manage annotations in PDF files with the Toolbox add-on. PDF annotations let you add comments, suggestions, and markup-like shapes and highlights to PDFs. Annotations are not part of the page content as they are applied on the top of a page. In contrast to ordinary page content, many annotation types behave interactively in PDF viewers. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddAnnotations)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddAnnotations)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddAnnotations)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddAnnotations)**. The Toolbox add-on supports these types of annotations: | Type | Annotation name | | --------------- | ---------------------- | | Text Markup | `Highlight``Popup``StickyNote``StrikeThrough``Underline``FreeText` | | Shape | `Ellipse``Ink``Line``Polygon``PolyLine``Rectangle``Squiggly` | | Navigation | `InternalLink``WebLink` | | Stamp | `TextStamp``CustomStamp` | | File | `FileAttachment` | **Steps to add annotations to a document**: 1. [Read the input document](#read-the-input-document) 2. [Copy document-wide data](#copy-document-wide-data) 3. [Copy and annotate the input pages](#copy-and-annotate-the-input-pages) 4. [Add copied pages to the output document](#add-copied-pages-to-the-output-document) 5. [Full example](#full-example) :::note[Before you begin] You need to **[Initialize the Toolbox add-on license](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/#initialize-the-toolbox-add-on-license)**. ## Read the input document Read the PDF file you want to annotate by loading the input document from the file system into a read-only input `Document` object. At the same time, create a writeable output `Document` object that contains the annotated output PDF file. **.NET:** ```csharp // Open input document using (Stream inStream = new FileStream(inPath, FileMode.Open, FileAccess.Read)) using (Document inDoc = Document.Open(inStream, null)) { // Create output document using Stream outStream = new FileStream(outPath, FileMode.Create, FileAccess.ReadWrite); using Document outDoc = Document.Create(outStream, inDoc.Conformance, null); ``` **Java:** ```java try (// Open input document FileStream inStream = new FileStream(inPath, FileStream.Mode.READ_ONLY); Document inDoc = Document.open(inStream, null); // Create file stream FileStream outStream = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW)) { try (// Create output document Document outDoc = Document.create(outStream, inDoc.getConformance(), null)) { ``` ## Copy document-wide data In the Toolbox add-on, you always start with an empty output document (unlike the Pdftools SDK). To retain document-wide information you must explicitly copy it from the input document to the output. Document-wide information includes: - Metadata - Viewer settings - Embedded files You can control which document-wide information is kept and which is removed using the `CopyDocumentData` function. In this example, all document-wide information is copied from the input document to the output document. **.NET:** ```csharp // Copy document-wide data CopyDocumentData(inDoc, outDoc); ``` **Java:** ```java // Copy document-wide data copyDocumentData(inDoc, outDoc); ``` **CopyDocumentData function** **.NET:** ```csharp private static void CopyDocumentData(Document inDoc, Document outDoc) { // Copy document-wide data // Output intent if (inDoc.OutputIntent != null) outDoc.OutputIntent = IccBasedColorSpace.Copy(outDoc, inDoc.OutputIntent); // Metadata outDoc.Metadata = Metadata.Copy(outDoc, inDoc.Metadata); // Viewer settings outDoc.ViewerSettings = ViewerSettings.Copy(outDoc, inDoc.ViewerSettings); // Associated files (for PDF/A-3 and PDF 2.0 only) FileReferenceList outAssociatedFiles = outDoc.AssociatedFiles; foreach (FileReference inFileRef in inDoc.AssociatedFiles) outAssociatedFiles.Add(FileReference.Copy(outDoc, inFileRef)); // Plain embedded files FileReferenceList outEmbeddedFiles = outDoc.PlainEmbeddedFiles; foreach (FileReference inFileRef in inDoc.PlainEmbeddedFiles) outEmbeddedFiles.Add(FileReference.Copy(outDoc, inFileRef)); } ``` **Java:** ```java private static void copyDocumentData(Document inDoc, Document outDoc) throws ToolboxException, IOException { // Copy document-wide data // Output intent if (inDoc.getOutputIntent() != null) outDoc.setOutputIntent(IccBasedColorSpace.copy(outDoc, inDoc.getOutputIntent())); // Metadata outDoc.setMetadata(Metadata.copy(outDoc, inDoc.getMetadata())); // Viewer settings outDoc.setViewerSettings(ViewerSettings.copy(outDoc, inDoc.getViewerSettings())); // Associated files (for PDF/A-3 and PDF 2.0 only) FileReferenceList outAssociatedFiles = outDoc.getAssociatedFiles(); for (FileReference inFileRef : inDoc.getAssociatedFiles()) outAssociatedFiles.add(FileReference.copy(outDoc, inFileRef)); // Plain embedded files FileReferenceList outEmbeddedFiles = outDoc.getPlainEmbeddedFiles(); for (FileReference inFileRef : inDoc.getPlainEmbeddedFiles()) outEmbeddedFiles.add(FileReference.copy(outDoc, inFileRef)); } ``` ## Copy and annotate the input pages When copying page content between documents, the [PageCopyOptions](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/T_PdfTools_Toolbox_Pdf_PageCopyOptions.htm) class lets you define which types of page information to copy. For example, you can choose to copy or remove information such as annotations, form fields, and structure elements to the output page. In this example, all page information except digital signatures is copied to the output document. The `CopyAndAddAnnotations` function copies the page content and selected page information from the first page of the input document. It then adds a `StickyNote`, an `Ellipse`, a `Highlight`, a `FreeText`, and a `WebLink` annotation to the page. **.NET:** ```csharp // Define page copy options PageCopyOptions copyOptions = new PageCopyOptions(); // Copy first page and add annotations Page outPage = CopyAndAddAnnotations(outDoc, inDoc.Pages[0], copyOptions); ``` **Java:** ```java // Define page copy options PageCopyOptions copyOptions = new PageCopyOptions(); // Copy first page and add annotations Page outPage = copyAndAddAnnotations(outDoc, inDoc.getPages().get(0), copyOptions); ``` **CopyAndAddAnnotations function** **.NET:** ```csharp private static Page CopyAndAddAnnotations(Document outDoc, Page inPage, PageCopyOptions copyOptions) { // Copy page to output document Page outPage = Page.Copy(outDoc, inPage, copyOptions); // Make a RGB color space ColorSpace rgb = ColorSpace.CreateProcessColorSpace(outDoc, ProcessColorSpaceType.Rgb); // Get the page size for positioning annotations Size pageSize = outPage.Size; // Get the output page's list of annotations for adding annotations AnnotationList annotations = outPage.Annotations; // Create a sticky note and add to output page's annotations Paint green = Paint.Create(outDoc, rgb, new double[] { 0, 1, 0 }, null); Point stickyNoteTopLeft = new Point() { X = 10, Y = pageSize.Height - 10 }; StickyNote stickyNote = StickyNote.Create(outDoc, stickyNoteTopLeft, "Hello world!", green); annotations.Add(stickyNote); // Create an ellipse and add to output page's annotations Paint blue = Paint.Create(outDoc, rgb, new double[] { 0, 0, 1 }, null); Paint yellow = Paint.Create(outDoc, rgb, new double[] { 1, 1, 0 }, null); Rectangle ellipseBox = new Rectangle() { Left = 10, Bottom = pageSize.Height - 60, Right = 70, Top = pageSize.Height - 20 }; EllipseAnnotation ellipse = EllipseAnnotation.Create(outDoc, ellipseBox, new Stroke(blue, 1.5), yellow); annotations.Add(ellipse); // Create a free text and add to output page's annotations Paint yellowTransp = Paint.Create(outDoc, rgb, new double[] { 1, 1, 0 }, new Transparency(0.5)); Rectangle freeTextBox = new Rectangle() { Left = 10, Bottom = pageSize.Height - 170, Right = 120, Top = pageSize.Height - 70 }; FreeText freeText = FreeText.Create(outDoc, freeTextBox, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", yellowTransp); annotations.Add(freeText); // A highlight and a web-link to be fitted on existing page content elements Highlight highlight = null; WebLink webLink = null; // Extract content elements from the input page ContentExtractor extractor = new ContentExtractor(inPage.Content); foreach (ContentElement element in extractor) { // Take the first text element if (highlight == null && element is TextElement textElement) { // Get the quadrilaterals of this text element QuadrilateralList quadrilaterals = new QuadrilateralList(); foreach (TextFragment fragment in textElement.Text) quadrilaterals.Add(fragment.Transform.TransformRectangle(fragment.BoundingBox)); // Create a highlight and add to output page's annotations highlight = Highlight.CreateFromQuadrilaterals(outDoc, quadrilaterals, yellow); annotations.Add(highlight); } // Take the first image element if (webLink == null && element is ImageElement) { // Get the quadrilateral of this image QuadrilateralList quadrilaterals = new QuadrilateralList(); quadrilaterals.Add(element.Transform.TransformRectangle(element.BoundingBox)); // Create a web-link and add to the output page's links webLink = WebLink.CreateFromQuadrilaterals(outDoc, quadrilaterals, "https://www.pdf-tools.com"); Paint red = Paint.Create(outDoc, rgb, new double[] { 1, 0, 0 }, null); webLink.BorderStyle = new Stroke(red, 1.5); outPage.Links.Add(webLink); } // Exit loop if highlight and webLink have been created if (highlight != null && webLink != null) break; } // return the finished page return outPage; } ``` **Java:** ```java private static Page copyAndAddAnnotations(Document outDoc, Page inPage, PageCopyOptions copyOptions) throws ConformanceException, CorruptException, IOException, UnsupportedFeatureException { // Copy page to output document Page outPage = Page.copy(outDoc, inPage, copyOptions); // Make a RGB color space ColorSpace rgb = ColorSpace.createProcessColorSpace(outDoc, ProcessColorSpaceType.RGB); // Get the page size for positioning annotations Size pageSize = outPage.getSize(); // Get the output page's list of annotations for adding annotations AnnotationList annotations = outPage.getAnnotations(); // Create a sticky note and add to output page's annotations Paint green = Paint.create(outDoc, rgb, new double[] { 0, 1, 0 }, null); Point stickyNoteTopLeft = new Point(10, pageSize.height - 10 ); StickyNote stickyNote = StickyNote.create(outDoc, stickyNoteTopLeft, "Hello world!", green); annotations.add(stickyNote); // Create an ellipse and add to output page's annotations Paint blue = Paint.create(outDoc, rgb, new double[] { 0, 0, 1 }, null); Paint yellow = Paint.create(outDoc, rgb, new double[] { 1, 1, 0 }, null); Rectangle ellipseBox = new Rectangle(10, pageSize.height - 60, 70, pageSize.height - 20); EllipseAnnotation ellipse = EllipseAnnotation.create(outDoc, ellipseBox, new Stroke(blue, 1.5), yellow); annotations.add(ellipse); // Create a free text and add to output page's annotations Paint yellowTransp = Paint.create(outDoc, rgb, new double[] { 1, 1, 0 }, new Transparency(0.5)); Rectangle freeTextBox = new Rectangle(10, pageSize.height - 170, 120, pageSize.height - 70); FreeText freeText = FreeText.create(outDoc, freeTextBox, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", yellowTransp); annotations.add(freeText); // A highlight and a web-link to be fitted on existing page content elements Highlight highlight = null; WebLink webLink = null; // Extract content elements from the input page ContentExtractor extractor = new ContentExtractor(inPage.getContent()); for (ContentElement element : extractor) { // Take the first text element if (highlight == null && element instanceof TextElement) { TextElement textElement = (TextElement)element; // Get the quadrilaterals of this text element QuadrilateralList quadrilaterals = new QuadrilateralList(); for (TextFragment fragment : textElement.getText()) quadrilaterals.add(fragment.getTransform().transformRectangle(fragment.getBoundingBox())); // Create a highlight and add to output page's annotations highlight = Highlight.createFromQuadrilaterals(outDoc, quadrilaterals, yellow); annotations.add(highlight); } // Take the first image element if (webLink == null && element instanceof ImageElement) { // Get the quadrilateral of this image QuadrilateralList quadrilaterals = new QuadrilateralList(); quadrilaterals.add(element.getTransform().transformRectangle(element.getBoundingBox())); // Create a web-link and add to the output page's links webLink = WebLink.createFromQuadrilaterals(outDoc, quadrilaterals, "https://www.pdf-tools.com"); Paint red = Paint.create(outDoc, rgb, new double[] { 1, 0, 0 }, null); webLink.setBorderStyle(new Stroke(red, 1.5)); outPage.getLinks().add(webLink); } // Exit loop if highlight and webLink have been created if (highlight != null && webLink != null) break; } // return the finished page return outPage; } ``` ## Add copied pages to the output document After copying and adding annotations to the page, the annotated page is added to the output document. After this step, it is no longer possible to change the page. Finally, the remaining pages are copied and added to the output document as a [PageList](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/Methods_T_PdfTools_Toolbox_Pdf_PageList.htm). **.NET:** ```csharp // Add the page to the output document's page list outDoc.Pages.Add(outPage); // Copy the remaining pages and add to the output document's page list PageList inPages = inDoc.Pages.GetRange(1, inDoc.Pages.Count - 1); PageList outPages = PageList.Copy(outDoc, inPages, copyOptions); outDoc.Pages.AddRange(outPages); ``` **Java:** ```java // Add the page to the output document's page list outDoc.getPages().add(outPage); // Copy the remaining pages and add to the output document's page list PageList inPages = inDoc.getPages().subList(1, inDoc.getPages().size()); PageList outPages = PageList.copy(outDoc, inPages, copyOptions); outDoc.getPages().addAll(outPages); ``` ## Full example Get the full example on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddAnnotations)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddAnnotations)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddAnnotations)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddAnnotations)**. --- ## Add and remove content The Toolbox add-on lets you add content to a PDF such as text, watermarks, barcodes, and images. :::tip[Quick start with a code example - Add text to a PDF] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddText)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddText)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddText)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddText)**. ## Content types The Toolbox add-on supports adding these types of content: - `Text` - `Image` - `Image Mask` - `Path` ## Add and remove content There is a wide range of use cases for these content types: | Content type | Use case example | | --------------- | ---------------------- | | Text | Add text to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddText), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddText), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddText), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddText))Add a barcode to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddBarcode), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddBarcode), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddBarcode), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddBarcode))Add line numbers to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddLineNumbers), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddLineNumbers), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddLineNumbers), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddLineNumbers))Add a stamp to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddStamp), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddStamp), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddStamp), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddStamp))Add page numbers to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/StampPageNumber), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/StampPageNumber), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/StampPageNumber), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/StampPageNumber)) Layout text in a PDF page ([C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/LayoutText), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/LayoutText), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/LayoutText)) Remove glyphs from a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveGlyphs), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveGlyphs), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveGlyphs), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveGlyphs)) Remove white text from a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveWhiteText), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveWhiteText), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveWhiteText), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveWhiteText)) | | Image | Add a QR code (Data Matrix) to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddDataMatrix), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddDataMatrix), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddDataMatrix), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddDataMatrix))Add an image to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddImage), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddImage), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddImage), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddImage)) | | Image Mask | Add an image mask to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddImageMask), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddImageMask), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddImageMask), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddImageMask)) | | Path | Add a vector graphic to a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddVectorGraphics), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddVectorGraphics), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddVectorGraphics), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddVectorGraphics)) | --- ## Extract The Toolbox add-on lets you extract information such as text, images, and signatures from a PDF document. You can also extract document attributes like the conformance level, whether the document is encrypted or protected, and metadata like author, title, and creation date. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/TextExtraction)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TextExtraction)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TextExtraction)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TextExtraction)**. ## Extract text Learn how to extract text content from a PDF document using the Extract all text from PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/TextExtraction), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/TextExtraction), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/TextExtraction), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TextExtraction)) code example. This project also illustrates the use of heuristics to assemble text content into words and sentences based on their position on the page. ## Extract images Learn how to extract images from a PDF document using the Extract all images and image masks from a PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ImageExtraction), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ImageExtraction), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ImageExtraction), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ImageExtraction)) code example. The extract images functionality accepts an image embedded as a content element in a PDF file and outputs it as an image file. :::note[Output formats] - BMP - JPEG - JPEG2000 - JBIG2 - PNG - GIF - TIFF :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ImageExtraction)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ImageExtraction)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ImageExtraction)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ImageExtraction)**. ## Extract signatures Learn how to extract signature content from a PDF document using the List Signatures in PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListSignatures), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListSignatures), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListSignatures), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListSignatures)) code example. You can automatically extract signature information such as name, date, and contact information. For a guide to comprehensive validation of digital signatures, review [Validate signatures in a signed PDF document](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/sign-and-secure/sign/sign-validate) page. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListSignatures)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListSignatures)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListSignatures)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListSignatures)**. ## Extract document attributes and metadata Extract document attributes and metadata from a PDF document using the List document information of PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListInfo), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListInfo), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListInfo), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListInfo)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListInfo)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListInfo)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListInfo)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListInfo)**. --- ## Generate PDFs The Toolbox add-on lets you create new PDF files from scratch using C#, Java, and Python. After creating the PDF files, use the Toolbox add-on to [add content](https://www.pdf-tools.com/docs/toolbox-add-on/guides/edit), [add form fields](https://www.pdf-tools.com/docs/toolbox-add-on/guides/add-and-fill-form-fields), [manage metadata](https://www.pdf-tools.com/docs/toolbox-add-on/guides/manage-metadata), and more. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/LayoutText)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/LayoutText)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/LayoutText)**. ## Create a new PDF document Learn how to create a new PDF file using Layout text on PDF page ([C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/LayoutText), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/LayoutText), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/LayoutText)) code example. --- ## Manage metadata The Toolbox add-on lets you add, remove, and update metadata in a PDF document. Manage standard metadata fields such as the Author, Title, and Subject. You can also manage custom metadata fields and directly update the XMP metadata with your XML content. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddMetadata)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddMetadata)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddMetadata)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddMetadata)**. ## List document metadata Learn how to list document attributes and metadata from a PDF document using the List document information of PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListInfo), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListInfo), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListInfo), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListInfo)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/ListInfo)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/ListInfo)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/ListInfo)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/ListInfo)**. ## Add metadata Learn how to set metadata such as the author, title, and creator of a PDF document using the Add metadata to PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/AddMetadata), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/AddMetadata), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/AddMetadata), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddMetadata)) code example. Optionally, copy metadata from another PDF document or the content of an XMP metadata file. --- ## Layout for printing The Toolbox add-on lets you create a layout of a PDF document that is ready for printing. Flatten form fields, set page dimensions, set page orientation, and place multiple pages onto one page. ## Flatten form fields Flatten form fields in a PDF document using the Flatten form fields ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FlattenFormFields), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FlattenFormFields), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FlattenFormFields), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FlattenFormFields)) code example. This process turns the form field into non-interactive content while retaining its visual appearance. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FlattenFormFields)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FlattenFormFields)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FlattenFormFields)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FlattenFormFields)**. ## Set page dimensions Learn how to set the dimensions of a PDF page using the Fit pages to specific page format ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FitPage), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FitPage), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FitPage), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FitPage)) code example. In this project, you also learn how to detect the page orientation and automatically rotate and scale it if it doesn't fit the target page format. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/FitPage)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/FitPage)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/FitPage)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/FitPage)**. ## Set page orientation Learn how to adjust the orientation of a PDF page using the Set page orientation ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RotatePages), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RotatePages), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RotatePages), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RotatePages)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RotatePages)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RotatePages)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RotatePages)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RotatePages)**. ## Place multiple pages onto one page Learn how to place multiple PDF pages onto a single page using the Place multiple pages on one page ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/MultipleUp), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/MultipleUp), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/MultipleUp), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/MultipleUp)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/MultipleUp)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/MultipleUp)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/MultipleUp)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/MultipleUp)**. --- ## Redact The Toolbox add-on lets you remove and redact content from an input PDF document so that it is no longer present in the output document. You can remove entire pages or content like text, images, and paths. You can also apply targeted redaction by removing or replacing individual characters (glyphs) from text. ## Remove pages Learn how to remove specific pages from a PDF document using the Remove pages from PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/Split), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/Split), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/Split), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/Split)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/Split)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/Split)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/Split)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/Split)**. ## Remove content Learn how to iterate through the PDF to remove specific content using the Remove White Text from PDF ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveWhiteText), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveWhiteText), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveWhiteText), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveWhiteText)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveWhiteText)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveWhiteText)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveWhiteText)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveWhiteText)**. ## Remove individual characters (glyphs) Learn how to remove individual characters (glyphs) from text in a PDF document using the Remove glyphs ([C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveGlyphs), [C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveGlyphs), [Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveGlyphs), [Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveGlyphs)) code example. :::tip[Quick start with a code sample] Get the full sample on GitHub: **[C](https://github.com/pdf-tools/toolbox-examples-c/tree/main/RemoveGlyphs)**, **[C#](https://github.com/pdf-tools/toolbox-examples-csharp/tree/main/RemoveGlyphs)**, **[Java](https://github.com/pdf-tools/toolbox-examples-java/tree/main/RemoveGlyphs)**, and **[Python](https://github.com/pdf-tools/toolbox-examples-python/tree/main/RemoveGlyphs)**. --- ## Migrate from version 1.11 or earlier Toolbox add-on 1.12+ simplifies the Java project setup. Toolbox add-on loads the native library automatically at runtime, so you no longer need platform-specific dependencies or `System.load()` / `System.loadLibrary()` calls in your code. Learn how to replace the earlier setup for Maven, Gradle, and manual JAR management. ## Maven ### Remove the earlier setup In versions 1.11 and earlier, your `pom.xml` contained two dependencies: the main JAR and a platform-specific native artifact with a classifier such as `linux-x64`, `win-x64`, or `osx-arm64`: ```xml com.pdftools toolbox 1.11.1 com.pdftools toolbox 1.11.1 linux-x64 so ``` Your Java code also contained a `System.load()` or `System.loadLibrary()` call to load the native binary before using Toolbox add-on: ```java // Remove this line System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.1/toolbox-1.11.1-linux-x64.so"); ``` ### Add the new setup Replace both dependencies with a single dependency. Remove all `System.load()` and `System.loadLibrary()` calls for Toolbox add-on from your code. ```xml com.pdftools toolbox 1.12.0 ``` This single dependency includes native binaries for all supported platforms. Toolbox add-on loads them automatically at runtime. ## Gradle ### Remove the earlier setup In versions 1.11 and earlier, your `build.gradle` contained two dependencies: the main JAR and a platform-specific native artifact: ```groovy // Remove this entire block implementation 'com.pdftools:toolbox:1.11.1' implementation 'com.pdftools:toolbox:1.11.1:linux-x64@so' ``` Your Java code also contained a `System.load()` or `System.loadLibrary()` call: ```java // Remove this line System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.11.1/toolbox-1.11.1-linux-x64.so"); ``` ### Add the new setup Replace both dependencies with a single dependency. Remove all `System.load()` and `System.loadLibrary()` calls for Toolbox add-on from your code. ```groovy implementation 'com.pdftools:toolbox:1.12.0' ``` This single dependency includes native binaries for all supported platforms. Toolbox add-on loads them automatically at runtime. ## Manual JAR management ### Remove the earlier setup In versions 1.11 and earlier, you downloaded a product kit ZIP that contained a JAR file and a `lib` directory with platform-specific native binaries: ``` lib ├── linux-x64 ├── linux-arm64 ├── osx-arm64 ├── osx-x64 ├── win-x64 ├── win-x86 └── win-arm64 ``` Your Java code contained a `System.load()` or `System.loadLibrary()` call to load the correct native binary at runtime: ```java // Remove these lines System.load(new File("lib/linux-x64/libPdfTools_Toolbox.so").getAbsolutePath()); // or System.loadLibrary("PdfTools_Toolbox"); ``` ### Add the new setup 1. Delete the earlier JAR file and the `lib` directory with native binaries (`.dll`, `.so`, `.dylib` files) from your project. 1. Download the following JARs from Maven Central: - [`toolbox-1.12.0.jar`](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.0/toolbox-1.12.0.jar) (binding layer; [sources JAR](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.0/toolbox-1.12.0-sources.jar), [Javadoc JAR](https://repo1.maven.org/maven2/com/pdftools/toolbox/1.12.0/toolbox-1.12.0-javadoc.jar)) - [`toolbox-native-1.12.0.jar`](https://repo1.maven.org/maven2/com/pdftools/toolbox-native/1.12.0/toolbox-native-1.12.0.jar) (native libraries) 1. Add both JARs to your project's classpath. 1. Remove all `System.load()` and `System.loadLibrary()` calls for Toolbox add-on from your code. The `toolbox-native` JAR bundles the native libraries, and Toolbox add-on loads them automatically at runtime. ## Further information - For the full setup instructions, see the [Java getting started guide](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-java). - For other changes in version 1.12, see the [release notes](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes). --- ## Toolbox add-on release notes Learn about the changes, additions and fixes of the Toolbox add-on. ### Version 1.12.1 24 April 2026 #### Fixed - Before this update, `Image.Redact()` redacted only the base image samples. As a consequence, when an image carried an image mask, the original pixels in the redacted area remained recoverable through the mask stream. With this release, redaction also clears the matching region in the image's mask stream when present. As a result, the redacted area can no longer be reconstructed from masking resources attached to the same image. - Before this release, reading a document's `PlainEmbeddedFiles` collection (the files attached to a PDF) caused an access violation on certain documents. As a consequence, applications that enumerated embedded files could crash. With this release, the collection is read safely on the affected documents. - Prior to this update, `CheckBox.CheckedExportName` returned an empty value for checkboxes created programmatically with `CheckBox.Create()` after the document was saved and reopened with Toolbox add-on. As a consequence, PDF readers such as Adobe Acrobat displayed a blank export value. With this update, `CheckedExportName` returns the expected default value `Yes` after save and reopen. - Before this update, extracting page content with `ContentExtractor` and re-appending it with `ContentGenerator` added an extra layer of graphics-state nesting each time. As a consequence, repeated extract-and-reappend operations pushed the document past the PDF/A nesting limit, and the result could no longer be converted to PDF/A. With this update, `ContentExtractor` and `ContentGenerator` no longer add redundant nesting. As a result, repeated extract-and-reappend operations preserve PDF/A convertibility. - Before this update, opening a malformed PDF containing nested object streams caused unbounded recursion when the affected objects were resolved. As a consequence, the process crashed with a stack overflow on the affected documents. With this release, the loader detects the cycle and reports a clean processing error. As a result, malformed input can no longer crash applications using the Toolbox add-on. ### Version 1.12.0 11 March 2026 #### Changed - **HEIF/HEIC codec library dynamically linked** The native library requires the HEIF/HEIC decoding library at load time, even if your application doesn't use HEIF/HEIC functionality. If the decoding library isn't found, the native library fails to load. The required binaries are included in the distribution, but ensure your service, container layout, library search paths, and permissions allow the library to be found. **Action:** After updating, verify that your deployment loads correctly even if HEIF/HEIC processing is not used. - **JBIG2 decoding update** The JBIG2 decoding implementation has been replaced. JBIG2-encoded images render identically, but error messages related to JBIG2 processing may differ from previous versions. **Action:** If you process PDFs with JBIG2-encoded images, consider validating against a representative document set. - **Updated font substitution for missing fonts (including PDF/A)** When PDFs reference fonts that aren't embedded and are unavailable on the host, the software substitutes fallback fonts. The updated fallback fonts support a larger glyph set and better fitting to original glyph dimensions. Layout should remain stable, but visual appearance differs from both the original font and previous versions. **Action:** If exact reproduction is required, install the original font in your environment. - **ZapfDingbats font delivery change** ZapfDingbats is no longer shipped. The fallback font URW++ D050000L.ttf is used instead, but it doesn't provide full coverage and may differ slightly in appearance. **Action:** If exact ZapfDingbats reproduction is required, install the font in your environment. - **Refreshed internal mapping tables** Character mapping tables used for Unicode and glyph mapping have been updated. Changes are primarily additive (new code points) with occasional correctness fixes. - **Java: native library loaded automatically** Before this release, Java applications had to explicitly locate and load the Toolbox add-on native binary using `System.load()` or `System.loadLibrary()` before calling any SDK function. With this release, the native binary is loaded automatically at runtime. The Maven dependency has also been simplified: the platform-specific native artifact classifier is no longer needed. **Action:** Remove any `System.load()` or `System.loadLibrary()` calls for the Toolbox add-on native library from your code. If you use Maven or Gradle, replace the two-dependency block (main JAR + native artifact) with a single dependency on `toolbox`. If you manage JARs manually, ensure both [`toolbox`](https://repo1.maven.org/maven2/com/pdftools/toolbox/) and [`toolbox-native`](https://repo1.maven.org/maven2/com/pdftools/toolbox-native/) JARs are on your classpath, and remove any native binaries (`.dll`, `.so`, `.dylib`) you previously placed in your project. Refer to the [Java getting started guide](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-java) for the updated configuration. - Upgraded libxml2 from version 2.10.3 to 2.15.0. Error messages related to XML processing may differ from previous versions. #### Fixed - Debug-level log messages are written to the file output sink when file logging is configured via `PDF_TRACE_OUTPUT` or `PDFT_LOG_OUTPUT`. - `CheckBox.CheckedExportName` returned an empty value when the checkbox `/Opt` entry was empty or invalid. The correct value is returned. - Fixed an access violation when processing certain documents. - Before this update, copying a page with `DoNotCopyContent` set to `true` caused image resources from the source page to be included in the output document. As a consequence, in workflows that copied a page without its content and then selectively copied content elements, the output file grew significantly with each iteration. With this release, image resources aren't included when copying a page without its content. - Before this update, on Linux, PDF dates were computed using the UTC offset of the current time instead of the UTC offset applicable to the date being processed. As a consequence, PDF dates could be off by one hour when the document's date and the current time fell in different daylight saving time (DST) periods. With this release, the UTC offset is correctly derived from the date being processed. - Before this update, the JBIG2 decoder placed no limit on memory allocations, which could cause excessive memory consumption when processing PDFs with malformed or unusually large JBIG2-encoded images. With this release, JBIG2 memory allocation is capped at 2 GB. ### Version 1.11.1 17 December 2025 #### Fixed - Toolbox add-on now supports using a proxy for license validation. For more information, review [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/#configure-proxy) in the Toolbox add-on licensing documentation. ### Version 1.11.0 29 October 2025 #### Added - Added `ContentGenerator.TagAsArtifact` method, which lets you tag all content created after its call as an artifact. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a197194d012812cbc5791ebd524dc3696), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/javadoc/com/pdftools/toolbox/pdf/content/ContentGenerator.html#tagAsArtifact(com.pdftools.toolbox.pdf.content.ArtifactType)), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAsArtifact.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.11/pydocs/_autosummary/pdftools_toolbox.pdf.content.content_generator.html#pdftools_toolbox.pdf.content.content_generator.ContentGenerator.tag_as_artifact). - Enhanced logging configuration environment variables: - `PDFT_LOG_OUTPUT` for output control, replacing `PDF_TRACE_OUTPUT`. The `PDF_TRACE_OUTPUT` also remains supported for backward compatibility. - `PDFT_LOG` for log level filters. The comma-separated format: `*:error,libbase:info`, where `*` sets the default level. #### Changed - Switched from the zlib to zlib-ng library, significantly improving performance when compressing and decompressing Flate streams by using SIMD instructions. #### Fixed - Gray color space output intent is set correctly. - Widget annotation appearance generation correctly checks for rich text value (RV) entry instead of rich text style (DS) entry when determining whether to create appearance streams. ### Version 1.10.0 16 September 2025 #### Added - Raw strings of text elements can be exposed as arrays of bytes. As a result, developers who use the Toolbox add-on can work directly with the underlying encoded text data for advanced processing and custom workflows. For more information, review these API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#aa4353fe4477ffe98b8ea261e64121d85), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_TextFragment_RawString.htm), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/javadoc/com/pdftools/toolbox/pdf/content/TextFragment.html#getRawString()), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/pydocs/_autosummary/pdftools_toolbox.pdf.content.text_fragment.html#pdftools_toolbox.pdf.content.text_fragment.TextFragment.raw_string). - Introduced a new method for retrieving the resolution of image masks. Find more details in the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/latest/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a38e3da6daeef207ff478c34fed2fa5c6), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/latest/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ImageMask_GetResolution.htm), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.10/javadoc/com/pdftools/toolbox/pdf/content/ImageMask.html#getResolution(com.pdftools.toolbox.geometry.real.AffineTransform)), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/latest/pydocs/_autosummary/pdftools_toolbox.pdf.content.image_mask.html#pdftools_toolbox.pdf.content.image_mask.ImageMask.get_resolution). #### Fixed - Resolved an issue using an uninitialized variable that could cause unpredictable behavior during PNG processing. - Fixed a stack buffer overflow when creating annotation appearances. - Corrected glyph position problems caused by improper handling of adjustment values. - Ensured the `GTS_PDFX` output intent is correctly copied into the output document to maintain PDF/X compliance. The `GTS_PDFX` defines the standardized printing output intent for PDF/X files. - Fixed an infinite loop that could occur during optimization for specific malformed PDF files. - Addressed an access violation related to cross-reference (xref) tables, preventing potential crashes. ### Version 1.9.0 29 July 2025 #### Added - Completed basic PDF/Universal Accessibility (PDF/UA) functionality: - Enabled reading of existing logical structure through `Pdf.Structure` API. - Added getter and setter methods for logical structure attributes: `AltT`,`ActualT`, `E`, and `Lang` - Extended the API declaring PDF/UA compliance by setting the `Marked` flag and embedding the `pdfuaid` in XMP metadata. - Added developer guides for accessing and creating logical structure in PDF documents. For more information, review [Accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/) section with three guides: [Create an accessible PDF from scratch](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/create-accessible-pdf), [Add logical structure to an existing PDF](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/add-logical-structure-to-existing-pdf), and [Read PDF logical structure](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/read-logical-structure) - Added samples for creating accessible PDF/UA with logical structure, reading logical structure from tagged PDF documents, and adding logical structure during PDF remediation. #### Changed - Removed library load and unload messages from Python bindings. - Replaced misleading `ArgumentException` with `CorruptException` for incorrect AF entry in PDF catalog. #### Fixed - Font name decoding for Type0 fonts on Linux and macOS to preserve Unicode characters. - Malformed import in native\_base.py that caused errors in Python bindings. - Fixed blank pages caused by incorrect indirect color space references in inline images. - Fixed unexpected termination when processing image dictionaries with an empty `/Filter` array. - Fixed text coordinate errors caused by specific usage of `q` and `Q` operators. - Fixed error reporting for non-UTF8 colorant name on Linux and macOS. - Font name decoding on Linux and macOS to align behavior with Windows. - Removed stray null terminators from strings returned by the Python interface. ### Version 1.8.0 19 June 2025 #### Added - The Toolbox add-on natively supports Linux ARM64 processor architecture. - `GetResolution` method was added to the `Image` class. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/cdoc/_pdf_tools___toolbox___ptx_pdf_content_8h.html#a30e928adb41205117fa1827e2a5dc773), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/javadoc/com/pdftools/toolbox/pdf/content/Image.html#getResolution(com.pdftools.toolbox.geometry.real.AffineTransform)), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_Image_GetResolution.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/pydocs/_autosummary/pdftools_toolbox.pdf.content.image.html#pdftools_toolbox.pdf.content.image.Image.get_resolution). - To support advanced cryptographic processing, the `SignatureField` class in the `PdfTools.Toolbox.Pdf` API exposes the raw digital signature blob through a read-only property `SignatureContents`. This property returns the exact binary value of the `/Contents` key from the PDF signature dictionary—equivalent to what was previously accessible through `Secure.GetSignature` in the legacy PDF Toolbox SDK. For more information, review the API references: [C](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/cdoc/_pdf_tools___toolbox___ptx_pdf_forms_8h.html#a5e92f70104b47a44551e6531d62fa508), [Java](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/javadoc/com/pdftools/toolbox/pdf/forms/SignedSignatureField.html#getSignatureContents()), [.NET](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_SignedSignatureField_SignatureContents.htm), [Python](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/pydocs/_autosummary/pdftools_toolbox.pdf.forms.signed_signature_field.html#pdftools_toolbox.pdf.forms.signed_signature_field.SignedSignatureField.signature_contents). #### Fixed - Previously, soft mask dimensions were not properly validated when a matte background was present. - Fixed PDF corruption and blank pages that occurred when cloning documents with certain image color spaces. ### Version 1.7.1 26 May 2025 #### Fixed - Resolved an issue where the `ContentExtractor` class reported incorrect glyph widths. - Addressed a problem with native library shutdown procedures that led to crashes or hangs when used through language bindings. ### Version 1.7.0 16 May 2025 #### Added - Code examples include links to Jupyter notebooks marked as the **Open in Colab** buttons. For more details, review [the Toolbox add-on code examples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples). - Improved multi-threaded handling of shared read-only data structures, allowing read-only configuration data to be shared safely between threads. ### Version 1.6.1 14 April 2025 #### Added - With this release, we are launching a new [Python Jupyter notebooks repository](https://github.com/pdf-tools/components-code-sample-hub) demonstrating the core functionality of the Toolbox add-on, including step-by-step examples for key features and use cases. #### Fixed - Previously, a crash occurred when IIS processes terminated, causing the Toolbox add-on DLL to unload without properly releasing its resources. This issue has been resolved, allowing the DLL to safely unload even when shutdown hooks fail to execute as expected. - Previously, PDFs utilizing Type 3 fonts appeared visually distorted after copying elements using `ContentElement.Copy`. This bug has been resolved, and the copied elements render correctly. ### Version 1.6.0 14 March 2025 #### Added - Improved support for HEIC files. #### Fixed - Prior to this release, the image conversion functionality was not working in Python. As of this update, the underlying issue is fixed by using aliases for imports when needed. Aliases are also added to some built-in methods from providers to fix inconsistencies. - Previously, radio buttons were improperly copied to the output documents. - Previously, under certain circumstances, a regression caused the decryption of encrypted PDFs to fail. The issue is fixed with this release. - Fixed a bug that caused crashes when handling JPEG images in the Toolbox add-on on 32-bit Windows system. - Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps. - The Python version of the content addition example [Add data matrix to PDF](https://github.com/pdf-tools/toolbox-examples-python/tree/main/AddDataMatrix) correctly places the matrix on the page. - The Python code example [Extract all text from PDF](https://github.com/pdf-tools/toolbox-examples-python/tree/main/TextExtraction) correctly reports page numbers when displaying extracted text to the console. ### Version 1.5.0 24 January 2025 #### Added - The Toolbox add-on natively supports Microsoft Windows ARM64 processor architecture. - Copy a page without copying its graphical content using the [DoNotCopyContent](https://api-reference.pdf-tools.com/pdfsdkxt/1.5/dotnet/html/P_PdfTools_Toolbox_Pdf_PageCopyOptions_DoNotCopyContent.htm) option. This is helpful for content removal workflows that have to fully preserve a page's metadata, annotations, and widgets. #### Fixed - A bug where the soft mask of an image was lost during copying has been fixed. - This update fixes an issue where the Toolbox add-on incorrectly handled x-advance information of the text painting operator, leading to wrongly placed glyphs. ### Version 1.4.0 28 November 2024 #### Added - Set the [Hidden](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_Widget_Hidden.htm) flag for `Widget` classes. When this flag is set, the `Widget` is invisible and unavailable to user interaction. - Get and set the [Locked](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_Widget_Locked.htm) flag for `Widget` class. When a `Widget` class is `Locked` its properties can't be changed. - As of this update, you can also get and set the `FontSize` for the [CombTextField](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_CombTextField.htm) and the [ListBox](https://api-reference.pdf-tools.com/pdfsdkxt/1.4/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_ListBox.htm) classes. ### Version 1.3.0 9 October 2024 #### Added - The [Pdf.Structure](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/N_PdfTools_Toolbox_Pdf_Structure.htm) namespace has been added to the Toolbox add-on. You can use the classes and methods in this namespace to add structure information ("tags") to the generated PDF content for use cases such as PDF accessibility. With this update, you can [Tag](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAs.htm) content created using the [ContentGenerator](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_ContentGenerator_TagAs.htm) and link the content to the document's [Structure Tree](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Structure_Tree.htm). You can also create custom tags by adding them to the document's [RoleMap](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Structure_RoleMap.htm). - As of this update, you can determine whether a font is embedded in a PDF by checking the [IsEmbedded](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_Font_IsEmbedded.htm) property of the [Font](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Content_Font.htm) object. - Redact a rectangular area of an image using the [Redact](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/M_PdfTools_Toolbox_Pdf_Content_Image_Redact.htm) method of the [Image](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Content_Image.htm) class. This changes the content of the image so that all pixels within the defined rectangle are set to the same color. #### Fixed - With this update, you can set the URI for the [LicensingService](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Sdk_LicensingService.htm) using the [Sdk](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Sdk.htm) class of the Toolbox add-on. Before this fix, the default value for the LicensingService was always used. - Before this update, the Toolbox add-on sometimes could terminate unexpectedly when: - Iterating through the [Content](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Page_Content.htm) of a [Page](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Page.htm). - Loading the [ExportName](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/P_PdfTools_Toolbox_Pdf_Forms_FieldNode_ExportName.htm) of a [FieldNode](https://api-reference.pdf-tools.com/pdfsdkxt/1.3/dotnet/html/T_PdfTools_Toolbox_Pdf_Forms_FieldNode.htm). The underlying issues were fixed. As a result, the Toolbox add-on no longer crashes in the described scenarios. ### Version 1.2.0 22 July 2024 #### Added - Image sampling accesses and handles the raw pixel data of an image in a sequential order without altering the resolution. This involves reading or setting the pixel values directly, often in the context of image processing or manipulation at the most detailed level. Get and set image samples using the Toolbox add-on. Review the [Image.Samples](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/P_PdfTools_Toolbox_Pdf_Content_Image_Samples.htm) property in the API documentation for more information. - As of this update, you can set the URL for the [Licensing Service](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/P_PdfTools_Toolbox_Sdk_LicensingService.htm) using the [Sdk Class](https://api-reference.pdf-tools.com/pdfsdkxt/1.2/dotnet/html/T_PdfTools_Toolbox_Sdk.htm) of the Toolbox add-on. This URL is used for trial licenses and page-based licenses. ### Version 1.1.0 28 June 2024 #### Added - Retrieve information about a content element's Optional Content Membership using the Toolbox add-on. Optional Content Membership is defined by Optional Content Groups (also called layers) whose state determines whether a content element is visible or invisible. - Retrieve the Rotation (`None`, `Clockwise`, `UpsideDown`, or `CounterClockwise`) of a page using the Toolbox add-on. ### Version 1.0.0 24 April 2024 #### Added - Integrated [the Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/) into the Pdftools SDK. All the functionality from the PDF Toolbox SDK is included with your Pdftools SDK license. --- ## Toolbox add-on technical specifications The Toolbox add-on provides low-level access to PDF content for C, C#, and Java, delivering advanced PDF manipulation capabilities. ## Functionality This list provides an overview of the core functionality of the Toolbox add-on with links to specific implementation guides: - [Accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/): Add logical structure and accessibility features to PDF documents. - [Add and fill form fields](https://www.pdf-tools.com/docs/toolbox-add-on/guides/add-and-fill-form-fields): Create interactive forms and fill form fields programmatically. - [Edit](https://www.pdf-tools.com/docs/toolbox-add-on/guides/edit): Add, remove, and modify content in PDF documents. - [Extract information](https://www.pdf-tools.com/docs/toolbox-add-on/guides/extract): Extract text, images, and other content from PDF documents. - [Generate PDFs](https://www.pdf-tools.com/docs/toolbox-add-on/guides/generate): Create PDF documents from scratch with full control over structure and content. - [Layout for printing](https://www.pdf-tools.com/docs/toolbox-add-on/guides/print): Configure page layouts and print settings for PDF documents. - [Manage annotations](https://www.pdf-tools.com/docs/toolbox-add-on/guides/annotate): Add, modify, and remove annotations in PDF documents. - [Manage metadata](https://www.pdf-tools.com/docs/toolbox-add-on/guides/manage-metadata): Read and write document metadata and properties. - [Redact](https://www.pdf-tools.com/docs/toolbox-add-on/guides/redact): Permanently remove sensitive information from PDF documents. You can use the same license key for the Pdftools SDK, the Pdftools SDK Shell Tool, and the Toolbox add-on. The Pdftools SDK and the Pdftools SDK Shell Tool don't require a trial license key, but the Toolbox add-on requires it. SDK Can be used without license Use with trial license Use with full license Pdftools SDK Yes, adds watermark. Adds watermark. No watermark. Pdftools SDK Shell Tool Toolbox add-on No, processing fails. Adds watermark. No watermark. ## Supported languages and frameworks The Toolbox add-on is available for multiple languages: | Language or framework | Minimal supported version | Getting started | |-----------------------|----------------------------------------------|----------------------------------------------| | C | GCC toolset 4.8+, CMake 3.16+ | [C](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-c) | | Java | Java 8+ | [Java](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-java) | | .NET | .NET/.NET Core 2.0+ or .NET Framework 4.6.1+ | [.NET](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-dotnet) | | Python | Python 3.6+ | [Python](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-python) | ## Supported operating systems The Toolbox add-on is available for multiple operating systems: | Operating system | Supported architecture and other dependencies | |---------------------------------------------------|----------------------------------------------------------------------| | Windows Client 7+ | x86 or x64 | | Windows Server 2008+ | x86 or x64 | | macOS 10.10+ | x64 or arm64 | | Linux (RHEL 6.9+, CentOS 6+, Oracle Linux 8+, Fedora 29+, Debian 10+, Ubuntu 22.04+) | x64 | | Other Linux distribution (glibc 2.34+) | Linux kernel 2.6+, GCC toolset 4.8+, glibc 2.34+, x64 | | Other Linux distribution (glibc 2.12+) | Linux kernel 2.6+, GCC toolset 4.1+, glibc 2.12+, x64 | ## Supported PDF versions The Toolbox add-on supports these PDF versions: | Version | Standard | | ------------ | ------------------------------------------------------ | | PDF 1.x | PDF Reference 1.3 - 1.6 | | PDF 1.7 | PDF 1.7 / ISO 32000-1 | | PDF 2.0 | PDF 2.0 / ISO 32000-2 | | PDF/A-1a | PDF/A-1a / ISO 19005-1 / Level A conformance | | PDF/A-1b | PDF/A-1b / ISO 19005-1 / Level B conformance | | PDF/A-2a | PDF/A-2a / ISO 19005-2 / Level A conformance | | PDF/A-2b | PDF/A-2b / ISO 19005-2 / Level B conformance | | PDF/A-2u | PDF/A-2u / ISO 19005-2 / Level U conformance | | PDF/A-3a | PDF/A-3a / ISO 19005-3 / Level A conformance | | PDF/A-3b | PDF/A-3b / ISO 19005-3 / Level B conformance | | PDF/A-3u | PDF/A-3u / ISO 19005-3 / Level U conformance | ## Supported image file formats The Toolbox add-on supports these image file formats: - JPEG - JPEG2000 - JBIG2 - PNG - GIF - TIFF - HEIC/HEIF :::tip[Get started] Try the Toolbox add-on with one of the **[Getting started guides](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/)**. --- ## Class: AnnotationRenderProperties The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. ## Constructors ### Constructor > **new AnnotationRenderProperties**(): `AnnotationRenderProperties` #### Returns `AnnotationRenderProperties` ## Accessors ### fixedRotation #### Get Signature > **get** **fixedRotation**(): `boolean` Specifies whether the annotation's appearance should remain fixed in orientation when the page is rotated. ##### Returns `boolean` #### Set Signature > **set** **fixedRotation**(`fixedRotation`): `void` ##### Parameters ###### fixedRotation `boolean` # *** ### fixedZoom #### Get Signature > **get** **fixedZoom**(): `boolean` Indicates whether the annotation's appearance should remain fixed in scale when the page's magnification level is changed. ##### Returns `boolean` #### Set Signature > **set** **fixedZoom**(`fixedZoom`): `void` ##### Parameters ###### fixedZoom `boolean` # *** ### renderToPrint #### Get Signature > **get** **renderToPrint**(): `boolean` Specifies whether the annotation should be printed when the page is printed, regardless of its visibility on the screen. ##### Returns `boolean` #### Set Signature > **set** **renderToPrint**(`renderToPrint`): `void` ##### Parameters ###### renderToPrint `boolean` # *** ### renderToScreen #### Get Signature > **get** **renderToScreen**(): `boolean` If set to false, the annotation will not be displayed on the screen and interaction with the user will be disabled. The annotation may be printed (depending on the setting of the `renderToPrint` flag), but it should be considered hidden for purposes of onscreen display and user interaction. ##### Returns `boolean` #### Set Signature > **set** **renderToScreen**(`renderToScreen`): `void` ##### Parameters ###### renderToScreen `boolean` ##### Returns `void` --- ## Abstract Class: DrawingAnnotation **`Experimental`** Base class for drawing annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Extended by - [`LineAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/LineAnnotation) - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation) ## Constructors ### Constructor > **new DrawingAnnotation**(`options`): `DrawingAnnotation` **`Experimental`** Creates a new `DrawingAnnotation` instance. #### Parameters ##### options [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions) Options used to initialize annotation. #### Returns `DrawingAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) **`Experimental`** ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#dispose) --- ## Class: EllipseAnnotation **`Experimental`** An ellipse drawing annotation ## Extends - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation) ## Constructors ### Constructor > **new EllipseAnnotation**(`options`): `EllipseAnnotation` **`Experimental`** Creates a new `EllipseAnnotation` instance. #### Parameters ##### options [`EllipseAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EllipseAnnotationOptions) Options used to initialize annotation. #### Returns `EllipseAnnotation` *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) **`Experimental`** *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#blendmode)* *** ### borderEffect #### Get Signature > **get** **borderEffect**(): [`BorderEffect`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BorderEffect) **`Experimental`** Gets the border effect of the ellipse annotation. ##### Returns [`BorderEffect`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BorderEffect) #### Set Signature > **set** **borderEffect**(`value`): `void` **`Experimental`** Sets the border effect of the ellipse annotation. ##### Parameters ###### value [`BorderEffect`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BorderEffect) # *** ### borderIntensity #### Get Signature > **get** **borderIntensity**(): `number` **`Experimental`** Gets the border intensity of the ellipse annotation. ##### Returns `number` #### Set Signature > **set** **borderIntensity**(`value`): `void` **`Experimental`** Sets the border intensity of the ellipse annotation. ##### Parameters ###### value `number` # *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) **`Experimental`** Gets the fill color of the ellipse annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) #### Set Signature > **set** **fillColor**(`value`): `void` **`Experimental`** Sets the fill color of the ellipse annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#iswidgetannotation)* *** ### lineColor #### Get Signature > **get** **lineColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) **`Experimental`** Gets the line color of the ellipse annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) #### Set Signature > **set** **lineColor**(`value`): `void` **`Experimental`** Sets the line color of the ellipse annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the ellipse annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the ellipse annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#dispose) --- ## Class: FreeTextAnnotation An annotation that displays text For a free-text annotation, the annotation's content is used as text to be displayed as the annotation's visual manifestation on the page. ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Constructors ### Constructor > **new FreeTextAnnotation**(`options`): `FreeTextAnnotation` Creates a new `FreeTextAnnotation` instance. #### Parameters ##### options [`FreeTextAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/FreeTextAnnotationOptions) Options used to initialize annotation. #### Returns `FreeTextAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#author)* *** ### backgroundColor #### Get Signature > **get** **backgroundColor**(): `string` Background color for the annotation. ##### Returns `string` #### Set Signature > **set** **backgroundColor**(`color`): `void` ##### Parameters ###### color `string` # *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Parameters ###### content `string` # *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#renderproperties)* *** ### richText #### Get Signature > **get** **richText**(): `string` A rich text string that shall be displayed in the popup window when the annotation is opened. ##### Returns `string` #### Set Signature > **set** **richText**(`richText`): `void` ##### Parameters ###### richText `string` # *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) Rotation of the annotation ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) #### Set Signature > **set** **rotation**(`rotation`): `void` ##### Parameters ###### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) # *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#dispose) --- ## Abstract Class: Layer\ # Abstract Class: Layer\ Abstract base class for a Layer, which is an event emitter that renders on a native HTML element. ## Extends - `EventEmitter`\<`LayerEventMap`\> ## Type Parameters ### T `T` *extends* `LayerNativeElementType` The type of the native element, either `HTMLDivElement` or `HTMLCanvasElement`. ## Constructors ### Constructor > **new Layer**\<`T`\>(`id`, `documentViewPage`): `Layer`\<`T`\> Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage `DocumentViewPage` The associated document view page. #### Returns `Layer`\<`T`\> *Overrides `EventEmitter.constructor`* ## Accessors ### documentViewPage #### Get Signature > **get** **documentViewPage**(): `DocumentViewPage` Gets the document view page associated with this layer. ##### Returns `DocumentViewPage` *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) The new size to be set. # ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from `EventEmitter.addEventListener`* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<`LayerEventMap`\[`K`\]\> The data associated with the event. *Inherited from `EventEmitter.dispatchEvent`* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from `EventEmitter.removeAllListeners`* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from `EventEmitter.removeEventListener` --- ## Class: LineAnnotation **`Experimental`** A line annotation ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation) ## Constructors ### Constructor > **new LineAnnotation**(`options`): `LineAnnotation` **`Experimental`** Creates a new `LineAnnotation` instance. #### Parameters ##### options [`LineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/LineAnnotationOptions) Options used to initialize annotation. #### Returns `LineAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#boundingbox)* *** ### color #### Get Signature > **get** **color**(): [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) **`Experimental`** Gets the color of the line annotation. ##### Returns [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) #### Set Signature > **set** **color**(`value`): `void` **`Experimental`** Sets the color of the line annotation. ##### Parameters ###### value [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) # *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#datemodified)* *** ### endPoint #### Get Signature > **get** **endPoint**(): [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) **`Experimental`** Gets the end point of the line annotation. ##### Returns [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) #### Set Signature > **set** **endPoint**(`value`): `void` **`Experimental`** Sets the end point of the line annotation. ##### Parameters ###### value [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#iswidgetannotation)* *** ### lineEndingAtEnd #### Get Signature > **get** **lineEndingAtEnd**(): [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) **`Experimental`** Gets the line ending at the end of the line annotation. ##### Returns [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) #### Set Signature > **set** **lineEndingAtEnd**(`value`): `void` **`Experimental`** Sets the line ending at the end of the line annotation. ##### Parameters ###### value [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) # *** ### lineEndingAtStart #### Get Signature > **get** **lineEndingAtStart**(): [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) **`Experimental`** Gets the line ending at the start of the line annotation. ##### Returns [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) #### Set Signature > **set** **lineEndingAtStart**(`value`): `void` **`Experimental`** Sets the line ending at the start of the line annotation. ##### Parameters ###### value [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the line annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the line annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#source)* *** ### startPoint #### Get Signature > **get** **startPoint**(): [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) **`Experimental`** Gets the start point of the line annotation. ##### Returns [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) #### Set Signature > **set** **startPoint**(`value`): `void` **`Experimental`** Sets the start point of the line annotation. ##### Parameters ###### value [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) # *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#dispose) --- ## Abstract Class: MarkupAnnotation Base class for all markup annotations ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) ## Extended by - [`FreeTextAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/FreeTextAnnotation) - [`TextMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/TextMarkupAnnotation) - [`NoteAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/NoteAnnotation) - [`StampAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/StampAnnotation) - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation) ## Constructors ### Constructor > **new MarkupAnnotation**(`options`): `MarkupAnnotation` #### Parameters ##### options [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) #### Returns `MarkupAnnotation` *Overrides `Annotation.constructor`* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** `abstract` **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** `abstract` **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** `abstract` **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** `abstract` **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** `abstract` **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation#dispose) --- ## Class: NoteAnnotation **`Experimental`** A sticky note annotation ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Constructors ### Constructor > **new NoteAnnotation**(`options`): `NoteAnnotation` **`Experimental`** Creates a new `NoteAnnotation` instance. #### Parameters ##### options [`NoteAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/NoteAnnotationOptions) Options used to initialize annotation. #### Returns `NoteAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#constructor)* ## Properties ### icon > **icon**: [`NoteAnnotationIcon`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/NoteAnnotationIcon) **`Experimental`** Icon to be displayed ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`NoteAnnotationColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/NoteAnnotationColor) **`Experimental`** Represents the fill color of the annotation in hexadecimal representation. ##### Returns [`NoteAnnotationColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/NoteAnnotationColor) #### Set Signature > **set** **fillColor**(`fillColor`): `void` **`Experimental`** ##### Parameters ###### fillColor [`NoteAnnotationColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/NoteAnnotationColor) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#subject)* *** ### topLeft #### Get Signature > **get** **topLeft**(): [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) **`Experimental`** Represents the top left point of the annotation on the page, specified as a `PdfPoint`. ##### Returns [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) #### Set Signature > **set** **topLeft**(`topLeft`): `void` **`Experimental`** ##### Parameters ###### topLeft [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) # *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#dispose) --- ## Class: PageRenderOptions **`Experimental`** ## Constructors ### Constructor > **new PageRenderOptions**(): `PageRenderOptions` **`Experimental`** #### Returns `PageRenderOptions` ## Properties ### noPrint > **noPrint**: `boolean` **`Experimental`** *** ### outputMedium? > `optional` **outputMedium**: `OutputMedium` **`Experimental`** The intended target for page rendering. When set to `OutputMedium.Print`, annotations with `printable=false` will not be rendered. ## Accessors ### annotationFilter #### Set Signature > **set** **annotationFilter**(`filter`): `void` **`Experimental`** ##### Parameters ###### filter () => `object` ##### Returns `void` --- ## Class: Point Represents a point in a two-dimensional coordinate system. ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`Point`\> ## Constructors ### Constructor > **new Point**(`x?`, `y?`): `Point` Creates a new `Point` instance with the specified coordinates. #### Parameters ##### x? `number` The X value (horizontal coordinate). ##### y? `number` The Y value (vertical coordinate). #### Returns `Point` ## Properties ### x > **x**: `number` The X value (horizontal coordinate). *** ### y > **y**: `number` The Y value (vertical coordinate). ## Methods ### clone() > **clone**(): `Point` Creates a deep copy of the object. #### Returns `Point` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone)* *** ### calculateCentroid() > `static` **calculateCentroid**(`points`): `Point` #### Parameters ##### points `Point`[] #### Returns `Point` *** ### calculateNormalLineYIntercept() > `static` **calculateNormalLineYIntercept**(`point`, `normalSlope`): `number` #### Parameters ##### point `Point` ##### normalSlope `number` #### Returns `number` *** ### calculatePerpendicularIntersection() > `static` **calculatePerpendicularIntersection**(`p1`, `p2`, `p3`): `Point` #### Parameters ##### p1 `Point` ##### p2 `Point` ##### p3 `Point` #### Returns `Point` *** ### calculateSlope() > `static` **calculateSlope**(`p1`, `p2`): `number` #### Parameters ##### p1 `Point` ##### p2 `Point` #### Returns `number` *** ### calculateYIntercept() > `static` **calculateYIntercept**(`point`, `slope`): `number` #### Parameters ##### point `Point` ##### slope `number` #### Returns `number` *** ### findIntersection() > `static` **findIntersection**(`slope1`, `yIntercept1`, `slope2`, `yIntercept2`): `Point` #### Parameters ##### slope1 `number` ##### yIntercept1 `number` ##### slope2 `number` ##### yIntercept2 `number` #### Returns `Point` --- ## Class: Quadrilateral\ # Class: Quadrilateral\ Represents a polygon with four sides and four corners. ## Type Parameters ### T `T` *extends* [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`Quadrilateral`\<`T`\>\> ## Constructors ### Constructor > **new Quadrilateral**\<`T`\>(`p1`, `p2`, `p3`, `p4`): `Quadrilateral`\<`T`\> Creates a new `Quadrilateral` instance with the specified corner coordinates. Accepts `Point` instances for each corner. #### Parameters ##### p1 `T` The Point representing the first corner. ##### p2 `T` The Point representing the second corner. ##### p3 `T` The Point representing the third corner. ##### p4 `T` The Point representing the fourth corner. #### Returns `Quadrilateral`\<`T`\> ### Constructor > **new Quadrilateral**\<`T`\>(`x1`, `y1`, `x2`, `y2`, `x3`, `y3`, `x4`, `y4`): `Quadrilateral`\<`T`\> Creates a new `Quadrilateral` instance with the specified corner coordinates. #### Parameters ##### x1 `number` The X coordinate of the first corner. ##### y1 `number` The Y coordinate of the first corner. ##### x2 `number` The X coordinate of the second corner. ##### y2 `number` The Y coordinate of the second corner. ##### x3 `number` The X coordinate of the third corner. ##### y3 `number` The Y coordinate of the third corner. ##### x4 `number` The X coordinate of the fourth corner. ##### y4 `number` The Y coordinate of the fourth corner. #### Returns `Quadrilateral`\<`T`\> ## Properties ### p1 > **p1**: `T` The `Point` representing the first corner. *** ### p2 > **p2**: `T` The `Point` representing the second corner. *** ### p3 > **p3**: `T` The `Point` representing the third corner. *** ### p4 > **p4**: `T` The `Point` representing the fourth corner. ## Accessors ### points #### Get Signature > **get** **points**(): `T`[] ##### Returns `T`[] ## Methods ### clone() > **clone**(): `Quadrilateral`\<`T`\> Creates a deep copy of the object. #### Returns `Quadrilateral`\<`T`\> A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone)* *** ### containsPoint() > **containsPoint**(`p`): `boolean` Checks if a given point is inside the quadrilateral. #### Parameters ##### p `T` The point to check, which is of type `T` extending `Point`. #### Returns `boolean` `true` if the point is inside the quadrilateral, otherwise `false`. --- ## Class: Rectangle\ # Class: Rectangle\ Represents a rectangle in a two-dimensional coordinate system. ## Type Parameters ### T `T` *extends* [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`Rectangle`\<`T`\>\> ## Constructors ### Constructor > **new Rectangle**\<`T`\>(`topLeft`, `size`): `Rectangle`\<`T`\> Creates a new `Rectangle` instance with the specified top-left corner and size. #### Parameters ##### topLeft `T` The top-left corner of the rectangle. ##### size [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) The size of the rectangle. #### Returns `Rectangle`\<`T`\> ### Constructor > **new Rectangle**\<`T`\>(`x`, `y`, `width`, `height`): `Rectangle`\<`T`\> Creates a new `Rectangle` instance with the specified coordinates and dimensions. #### Parameters ##### x `number` The X coordinate of the top-left corner. ##### y `number` The Y coordinate of the top-left corner. ##### width `number` The width of the rectangle. ##### height `number` The height of the rectangle. #### Returns `Rectangle`\<`T`\> ## Properties ### size > **size**: [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) The size of the rectangle. *** ### topLeft > **topLeft**: `T` The top-left corner of the rectangle. ## Accessors ### height #### Get Signature > **get** **height**(): `number` The height of the rectangle. ##### Returns `number` #### Set Signature > **set** **height**(`height`): `void` ##### Parameters ###### height `number` # *** ### width #### Get Signature > **get** **width**(): `number` The width of the rectangle. ##### Returns `number` #### Set Signature > **set** **width**(`width`): `void` ##### Parameters ###### width `number` # ## Methods ### clone() > **clone**(): `Rectangle`\<`T`\> Creates a deep copy of the object. #### Returns `Rectangle`\<`T`\> A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone)* *** ### calculateBoundingBox() > `static` **calculateBoundingBox**(`points`): `Rectangle`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point)\> Calculates the bounding box that encompasses a given set of points. #### Parameters ##### points [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point)[] An array of [Point](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) objects representing the points to enclose. #### Returns `Rectangle`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point)\> A Rectangle representing the bounding box of the points, or `null` if the input array is empty. #### Remarks This method determines the smallest rectangular area that fully contains all the provided points. It iterates through the points to find the minimum and maximum x and y coordinates, then constructs a Rectangle using those boundaries. If the input array is empty, the function returns `null`. --- ## Class: RectangleAnnotation **`Experimental`** A rectangle drawing annotation ## Extends - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation) ## Constructors ### Constructor > **new RectangleAnnotation**(`options`): `RectangleAnnotation` **`Experimental`** Creates a new `RectangleAnnotation` instance. #### Parameters ##### options [`RectangleAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/RectangleAnnotationOptions) Options used to initialize annotation. #### Returns `RectangleAnnotation` *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) **`Experimental`** *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) **`Experimental`** Gets the fill color of the rectangle annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) #### Set Signature > **set** **fillColor**(`value`): `void` **`Experimental`** Sets the fill color of the rectangle annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#iswidgetannotation)* *** ### lineColor #### Get Signature > **get** **lineColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) **`Experimental`** Gets the line color of the rectangle annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) #### Set Signature > **set** **lineColor**(`value`): `void` **`Experimental`** Sets the line color of the rectangle annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the rectangle annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the rectangle annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation#dispose) --- ## Class: RgbColor Represents a color with red, green and blue components. ## Extended by - [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`RgbColor`\> ## Constructors ### Constructor > **new RgbColor**(`colorString`): `RgbColor` Creates a new RgbColor instance from a string representation (hex, rgb or hsl). #### Parameters ##### colorString `string` The string representation of the color. #### Returns `RgbColor` #### Throws If the input string is not a valid color representation. ### Constructor > **new RgbColor**(`r?`, `g?`, `b?`): `RgbColor` Creates a new RgbColor instance. #### Parameters ##### r? `number` The red component of the color (0 to 255). ##### g? `number` The green component of the color (0 to 255). ##### b? `number` The blue component of the color (0 to 255). #### Returns `RgbColor` ## Properties ### b > **b**: `number` The blue component of the color (0 to 255). *** ### g > **g**: `number` The green component of the color (0 to 255). *** ### r > **r**: `number` The red component of the color (0 to 255). ## Accessors ### blue #### Get Signature > **get** **blue**(): `number` The intensity of blue in the described color as a value 0-255. ##### Returns `number` *** ### green #### Get Signature > **get** **green**(): `number` The intensity of green in the described color as a value 0-255. ##### Returns `number` *** ### red #### Get Signature > **get** **red**(): `number` The intensity of red in the described color as a value 0-255. ##### Returns `number` ## Methods ### clone() > **clone**(): `RgbColor` Creates a deep copy of the object. #### Returns `RgbColor` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone)* *** ### setRGB() > **setRGB**(`red`, `green`, `blue`): `void` Set a new color with all components at once #### Parameters ##### red `number` ##### green `number` ##### blue `number` *** ### toHexString() > **toHexString**(): `string` Converts the color to a hexadecimal string #### Returns `string` A string representation of the color in hexadecimal #### Example ```ts #330000 ``` *** ### toRgbaString() > **toRgbaString**(): `string` Converts the color to a CSS-formatted RGBA string. #### Returns `string` A string representation of the color in RGBA format. *** ### toRgbString() > **toRgbString**(): `string` Converts the color to a CSS-formatted RGB string. #### Returns `string` A string representation of the color in RGB format. --- ## Class: RgbaColor Represents a color with red, green, blue, and alpha components. ## Extends - [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`RgbaColor`\> ## Constructors ### Constructor > **new RgbaColor**(`colorString`): `RgbaColor` Creates a new RgbaColor instance from a string representation (hex, rgb, rgba or hsl). #### Parameters ##### colorString `string` The string representation of the color. #### Returns `RgbaColor` #### Throws If the input string is not a valid color representation. *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#constructor)* ### Constructor > **new RgbaColor**(`r?`, `g?`, `b?`, `a?`): `RgbaColor` Creates a new RgbaColor instance. #### Parameters ##### r? `number` The red component of the color (0 to 255). ##### g? `number` The green component of the color (0 to 255). ##### b? `number` The blue component of the color (0 to 255). ##### a? `number` The alpha (transparency) component of the color (0 to 1). #### Returns `RgbaColor` *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#constructor)* ## Properties ### a > **a**: `number` The alpha component of the color (0 to 1). *** ### b > **b**: `number` The blue component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`b`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#b)* *** ### g > **g**: `number` The green component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`g`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#g)* *** ### r > **r**: `number` The red component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`r`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#r)* ## Accessors ### blue #### Get Signature > **get** **blue**(): `number` The intensity of blue in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`blue`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#blue)* *** ### green #### Get Signature > **get** **green**(): `number` The intensity of green in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`green`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#green)* *** ### red #### Get Signature > **get** **red**(): `number` The intensity of red in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`red`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#red)* ## Methods ### clone() > **clone**(): `RgbaColor` Creates a deep copy of the object. #### Returns `RgbaColor` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone)* *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#clone)* *** ### setRGB() > **setRGB**(`red`, `green`, `blue`): `void` Set a new color with all components at once #### Parameters ##### red `number` ##### green `number` ##### blue `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`setRGB`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#setrgb)* *** ### toHexString() > **toHexString**(): `string` Converts the color to a hexadecimal string #### Returns `string` A string representation of the color in hexadecimal #### Example ```ts #330000 ``` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`toHexString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#tohexstring)* *** ### toRgbaString() > **toRgbaString**(): `string` Converts the color to a CSS-formatted RGBA string. #### Returns `string` A string representation of the color in RGBA format. *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`toRgbaString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#torgbastring)* *** ### toRgbString() > **toRgbString**(): `string` Converts the color to a CSS-formatted RGB string. #### Returns `string` A string representation of the color in RGB format. #### Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor).[`toRgbString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor#torgbstring) --- ## Abstract Class: ShapeAnnotation **`Experimental`** Base class for shape annotations ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation) ## Extended by - [`RectangleAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RectangleAnnotation) - [`EllipseAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/EllipseAnnotation) ## Constructors ### Constructor > **new ShapeAnnotation**(`options`): `ShapeAnnotation` **`Experimental`** Creates a new `ShapeAnnotation` instance. #### Parameters ##### options [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions) Options used to initialize annotation. #### Returns `ShapeAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation#dispose) --- ## Class: Size Represents the dimensions of an object in terms of width and height. ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable)\<`Size`\> ## Constructors ### Constructor > **new Size**(`width?`, `height?`): `Size` Creates a new Size instance with the specified width and height. #### Parameters ##### width? `number` The width of the object. ##### height? `number` The height of the object. #### Returns `Size` ## Properties ### height > **height**: `number` The height of the object. *** ### width > **width**: `number` The width of the object. ## Methods ### clone() > **clone**(): `Size` Creates a deep copy of the object. #### Returns `Size` A new instance that is a deep copy of the original object. #### Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable#clone) --- ## Class: StampAnnotation Base class for all stamp annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Constructors ### Constructor > **new StampAnnotation**(`options`): `StampAnnotation` Creates a new `StampAnnotation` instance. #### Parameters ##### options [`StampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/StampAnnotationOptions) Options used to initialize annotation. #### Returns `StampAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#creationdate)* *** ### data #### Get Signature > **get** **data**(): [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/StampData) An object representing the stamp annotation data, which depends on the subtype. ##### Returns [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/StampData) *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#dispose)* *** ### rebuild() > **rebuild**(`data`): `Promise`\<`void`\> **`Experimental`** Update stamp data and rebuild the annotation while keeping history and replies. #### Parameters ##### data [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/StampData) #### Returns `Promise`\<`void`\> --- ## Class: Stroke **`Experimental`** ## Constructors ### Constructor > **new Stroke**(): `Stroke` **`Experimental`** #### Returns `Stroke` ## Properties ### color > **color**: [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) **`Experimental`** The stroke color of the stroke. If the color is transparent, no stroke is visible. *** ### dashArray > **dashArray**: `number`[] **`Experimental`** A dash array defining a pattern of dashes and gaps to be used in drawing *** ### lineWidth > **lineWidth**: `number` **`Experimental`** The stroke width in points. If this value is 0, no stroke is drawn. #### Default Value `1` --- ## Class: TextMarkupAnnotation **`Experimental`** Base class for text markup annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Constructors ### Constructor > **new TextMarkupAnnotation**(`options`): `TextMarkupAnnotation` **`Experimental`** Creates a new `TextMarkupAnnotation` instance. #### Parameters ##### options [`TextMarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextMarkupAnnotationOptions) Options used to initialize annotation. #### Returns `TextMarkupAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) **`Experimental`** Retrieves the fill color used in the annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) The [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) representing the annotation's fill color. #### Set Signature > **set** **fillColor**(`v`): `void` **`Experimental`** Sets the fill color for the annotation. ##### Parameters ###### v [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) The new [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) to apply to the annotation. # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMaintainingAspectRatio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMarkupAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isMoveable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isResizable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isRotatable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isSelectable ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Pdf.Annotations.Annotation.isWidgetAnnotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#subject)* *** ### subtype #### Get Signature > **get** **subtype**(): [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/TextMarkupType) **`Experimental`** Retrieves the type of markup applied by this annotation. ##### Returns [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/TextMarkupType) The [TextMarkupType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/TextMarkupType) representing how the text is marked, such as highlight, underline, strikethrough, squiggly, or redact. *** ### textMarkupArea #### Get Signature > **get** **textMarkupArea**(): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\>[] **`Experimental`** Retrieves the area marked by this annotation. This represents the set of quadrilateral regions that highlight or mark portions of text within the document. ##### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\>[] An array of [Quadrilateral](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral) defining the marked-up area. *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) **`Experimental`** Pdf.Annotations.Annotation.type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#type)* *** ### underlyingText #### Get Signature > **get** **underlyingText**(): `string` **`Experimental`** Retrieves the text associated with the text markup annotation as a string. ##### Remarks This method provides a convenient way to access the text marked by the annotation, but it does not directly originate from the annotation object within the PDF structure. Due to potential complexities such as overlapping texts or watermarks, the returned string might not always precisely match the visually selected content. ##### Returns `string` The text associated with the annotation. ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation#dispose) --- ## Enumeration: AnnotationLockedState ## Enumeration Members ### All > **All**: `3` Fully locked, preventing deletion, modification of position and size, and changes to contents. *** ### Container > **Container**: `1` Locked to prevent modification or deletion of the annotation's position and size, excluding its contents. *** ### Content > **Content**: `2` Locked to prevent modifications to the annotation's contents, but allows changes to position and size. *** ### None > **None**: `0` No locking restrictions. --- ## Enumeration: AnnotationType Annotation Type ## Enumeration Members ### 3D > **3D**: `24` *** ### Caret > **Caret**: `12` *** ### Circle > **Circle**: `8` *** ### FileAttachment > **FileAttachment**: `15` *** ### FreeText > **FreeText**: `5` *** ### Ink > **Ink**: `13` *** ### InternalLink > **InternalLink**: `3` *** ### Line > **Line**: `6` *** ### Link > **Link**: `1` *** ### Movie > **Movie**: `17` *** ### Polygon > **Polygon**: `9` *** ### PolyLine > **PolyLine**: `10` *** ### Popup > **Popup**: `14` *** ### PrinterMark > **PrinterMark**: `20` *** ### Rectangle > **Rectangle**: `7` *** ### Redact > **Redact**: `23` *** ### Screen > **Screen**: `19` *** ### Sound > **Sound**: `16` *** ### Stamp > **Stamp**: `11` *** ### Text > **Text**: `0` *** ### TextMarkup > **TextMarkup**: `4` *** ### TrapNet > **TrapNet**: `21` *** ### Watermark > **Watermark**: `22` *** ### WebLink > **WebLink**: `2` *** ### Widget > **Widget**: `18` --- ## Enumeration: BlendMode Blend Mode controls how new content is painted and allows the new pixels to be affected by what has already been drawn. ## Enumeration Members ### add > **add**: `5` Commonly used to create an animated lightening dissolve effect between two images. *** ### darken > **darken**: `2` Replaces only the areas that are lighter than the blend color. Areas darker than the blend color don’t change. *** ### lighten > **lighten**: `3` Replaces only pixels that are darker than the blend color. Areas lighter than the blend color don’t change. *** ### multiply > **multiply**: `1` Multiplies the base color by the blend color, resulting in darker colors. *** ### normal > **normal**: `0` Applies color normally, with no interaction with the base colors. *** ### screen > **screen**: `4` Multiplies the inverse of the blend color by the base color, resulting in a bleaching effect. *** ### subtract > **subtract**: `6` Commonly used to create an animated darkening dissolve effect between two images. --- ## Enumeration: BorderEffect Types of border effects that can be applied to a drawing annotation. ## Enumeration Members ### Cloudy > **Cloudy**: `1` *** ### None > **None**: `0` --- ## Enumeration: DestinationType Supported PDF destination types ## Enumeration Members ### Direct > **Direct**: `1` A destination that directly points to a specific location in the document. *** ### FitHeight > **FitHeight**: `6` A destination fits the height of a page into the viewport. *** ### FitPage > **FitPage**: `4` A destination fits an entire page into the viewport. *** ### FitRectangle > **FitRectangle**: `0` A destination that fits a specified area of a page into the viewport. *** ### FitWidth > **FitWidth**: `5` A destination fits the width of a page into the viewport. *** ### LocationZoom > **LocationZoom**: `2` A destination that points to a specific location on the target page, using a specified zoom factor. The location is displayed in the top left corner of the viewport (if possible). *** ### Named > **Named**: `3` A destination that can be referred by name. --- ## Enumeration: FitMode Setting how the viewport will be fitted to the visible content ## Enumeration Members ### FitPage > **FitPage**: `2` Fit viewport to be able to show largest visible page in its entirety *** ### FitWidth > **FitWidth**: `1` Fit viewport to width of widest visible page *** ### None > **None**: `0` Do not fit --- ## Enumeration: LineEnding Line ending style controls how the end of a line is painted. ## Enumeration Members ### Butt > **Butt**: `6` (PDF 1.5) A short line at the endpoint perpendicular to the line itself *** ### Circle > **Circle**: `4` A circle filled with the annotation’s interior color, if any *** ### ClosedArrow > **ClosedArrow**: `2` Two short lines meeting in an acute angle as in the OpenArrow style and connected by a third line to form a triangular closed arrowhead filled with the annotation’s interior color, if any *** ### Diamond > **Diamond**: `5` A diamond shape filled with the annotation’s interior color, if any *** ### None > **None**: `0` No line ending *** ### OpenArrow > **OpenArrow**: `1` Two short lines meeting in an acute angle to form an open arrowhead *** ### ReversedClosedArrow > **ReversedClosedArrow**: `8` (PDF 1.5) A triangular closed arrowhead in the reverse direction from ClosedArrow *** ### ReversedOpenArrow > **ReversedOpenArrow**: `7` (PDF 1.5) Two short lines in the reverse direction from OpenArrow *** ### Slash > **Slash**: `9` (PDF 1.6) A short line at the endpoint approximately 30 degrees clockwise from perpendicular to the line itself *** ### Square > **Square**: `3` A square filled with the annotation’s interior color, if any --- ## Enumeration: NoteAnnotationIcon Icons for note annotation ## Enumeration Members ### Check > **Check**: `8` *** ### CheckMark > **CheckMark**: `9` *** ### Circle > **Circle**: `7` *** ### Comment > **Comment**: `0` *** ### Cross > **Cross**: `10` *** ### CrossHairs > **CrossHairs**: `11` *** ### Help > **Help**: `3` *** ### Insert > **Insert**: `6` *** ### Key > **Key**: `1` *** ### NewParagraph > **NewParagraph**: `4` *** ### Note > **Note**: `2` *** ### Paragraph > **Paragraph**: `5` *** ### RightArrow > **RightArrow**: `12` *** ### RightPointer > **RightPointer**: `13` *** ### Star > **Star**: `14` *** ### UpArrow > **UpArrow**: `15` *** ### UpLeftArrow > **UpLeftArrow**: `16` --- ## Enumeration: PageLayoutMode Setting how the pages will be arranged on the viewport. According to the PDF standard (PDF 1.7) ## Enumeration Members ### OneColumn > **OneColumn**: `1` Display the pages in one column. *** ### SinglePage > **SinglePage**: `0` Display one page at a time . *** ### TwoColumnLeft > **TwoColumnLeft**: `2` Display the pages in two columns, with odd-numbered pages on the left. *** ### TwoColumnRight > **TwoColumnRight**: `3` Display the pages in two columns, with odd-numbered pages on the right. *** ### TwoPageLeft > **TwoPageLeft**: `4` Display two pages at a time, with odd-numbered pages on the left. *** ### TwoPageRight > **TwoPageRight**: `5` Display two pages at a time, with odd-numbered pages on the right. --- ## Enumeration: PredefinedTextStampType An enum defining predefined text stamp types. ## Enumeration Members ### Approved > **Approved**: `0` *** ### AsIs > **AsIs**: `3` *** ### Completed > **Completed**: `14` *** ### Confidential > **Confidential**: `6` *** ### CustomStampText > **CustomStampText**: `18` *** ### Departmental > **Departmental**: `9` *** ### Draft > **Draft**: `12` *** ### Experimental > **Experimental**: `1` *** ### Expired > **Expired**: `4` *** ### Final > **Final**: `7` *** ### ForComment > **ForComment**: `10` *** ### ForPublicRelease > **ForPublicRelease**: `13` *** ### InformationOnly > **InformationOnly**: `17` *** ### NotApproved > **NotApproved**: `2` *** ### NotForPublicRelease > **NotForPublicRelease**: `5` *** ### PreliminaryResults > **PreliminaryResults**: `16` *** ### Sold > **Sold**: `8` *** ### TopSecret > **TopSecret**: `11` *** ### Void > **Void**: `15` --- ## Enumeration: Rotation Enumerates different rotation values in 90 degree steps. ## Enumeration Members ### Clockwise > **Clockwise**: `90` Represents 90 degree clockwise rotation. *** ### CounterClockwise > **CounterClockwise**: `270` Represents 270 degree counter-clockwise rotation. *** ### None > **None**: `0` Represents 0 degree rotation (no rotation). *** ### UpsideDown > **UpsideDown**: `180` Represents 180 degree rotation (upside down). --- ## Enumeration: StampAnnotationSubtype An enum defining stamp annotation subtypes. ## Enumeration Members ### Custom > **Custom**: `4` *** ### CustomText > **CustomText**: `1` *** ### Image > **Image**: `2` *** ### Pdf > **Pdf**: `3` *** ### PredefinedText > **PredefinedText**: `0` *** ### Undefined > **Undefined**: `5` --- ## Enumeration: StampColor An enum defining stamp colors. ## Enumeration Members ### Blue > **Blue**: `2` *** ### Green > **Green**: `1` *** ### Red > **Red**: `0` --- ## Enumeration: TextMarkupType Enum representing different types of text markup annotations used to visually highlight or mark text. This enum differentiates the various appearances that can be applied to marked-up areas within a document, such as highlighting, underlining, striking through text, or redacting. ## Enumeration Members ### Highlight > **Highlight**: `0` Highlights the entire marked area with a background color. *** ### Redact > **Redact**: `4` Marks the entire area for redaction. *** ### Squiggly > **Squiggly**: `3` Draws a squiggly (wavy) line under the baseline of the marked text. *** ### Strikethrough > **Strikethrough**: `2` Strikes through the text with a line parallel to the baseline. *** ### Underline > **Underline**: `1` Draws a line under the baseline of the marked text. *** ### Unknown > **Unknown**: `5` Represents an uninitialized or unknown annotation type. --- ## @pdftools/pdf-web-viewer ## Enumerations - [AnnotationLockedState](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) - [AnnotationType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) - [BlendMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) - [BorderEffect](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BorderEffect) - [DestinationType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/DestinationType) - [FitMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) - [LineEnding](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) - [NoteAnnotationIcon](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/NoteAnnotationIcon) - [PageLayoutMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) - [PredefinedTextStampType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PredefinedTextStampType) - [Rotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) - [StampAnnotationSubtype](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype) - [StampColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampColor) - [TextMarkupType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/TextMarkupType) ## Classes - [AnnotationRenderProperties](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) - [DrawingAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/DrawingAnnotation) - [EllipseAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/EllipseAnnotation) - [FreeTextAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/FreeTextAnnotation) - [Layer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Layer) - [LineAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/LineAnnotation) - [MarkupAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) - [NoteAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/NoteAnnotation) - [PageRenderOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/PageRenderOptions) - [Point](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) - [Quadrilateral](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral) - [Rectangle](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle) - [RectangleAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RectangleAnnotation) - [RgbaColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) - [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) - [ShapeAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/ShapeAnnotation) - [Size](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Size) - [StampAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/StampAnnotation) - [Stroke](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) - [TextMarkupAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/TextMarkupAnnotation) ## Interfaces - [Annotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) - [AnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions) - [Cloneable](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Cloneable) - [CustomStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/CustomStampAnnotationOptions) - [CustomTextStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/CustomTextStampAnnotationOptions) - [Destination](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Destination) - [Disposable](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Disposable) - [Document](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Document) - [DocumentSaveOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentSaveOptions) - [DocumentView](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentView) - [DrawingAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions) - [EllipseAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EllipseAnnotationOptions) - [EventHandler](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler) - [FreeTextAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/FreeTextAnnotationOptions) - [ImageStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ImageStampAnnotationOptions) - [InputFile](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputFile) - [InputUri](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputUri) - [LineAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/LineAnnotationOptions) - [MarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) - [NoteAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/NoteAnnotationOptions) - [Page](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) - [PdfStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PdfStampAnnotationOptions) - [PdfToolsViewer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PdfToolsViewer) - [Plugin](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugin) - [Plugins](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugins) - [PredefinedTextStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PredefinedTextStampAnnotationOptions) - [RectangleAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/RectangleAnnotationOptions) - [ShapeAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions) - [StampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/StampAnnotationOptions) - [TextFragment](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextFragment) - [TextMarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextMarkupAnnotationOptions) - [UIDocumentView](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/UIDocumentView) ## Type Aliases - [Cursor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/Cursor) - [DocumentEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap) - [DocumentPrintOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentPrintOptions) - [DocumentViewEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap) - [DocumentViewPoint](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint) - [EventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap) - [LicenseKey](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/LicenseKey) - [NoteAnnotationColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/NoteAnnotationColor) - [OverridableButtonEventType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/OverridableButtonEventType) - [PdfPoint](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) - [PluginsEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap) - [StampData](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/StampData) - [ThumbnailOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/ThumbnailOptions) - [ViewerConfig](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/ViewerConfig) --- ## Abstract Interface: Annotation Base class for all annotations. ## Extended by - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/MarkupAnnotation) ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Disposable) ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> # *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *** ### isMaintainingAspectRatio #### Get Signature > **get** `abstract` **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *** ### isMarkupAnnotation #### Get Signature > **get** `abstract` **isMarkupAnnotation**(): `boolean` Indicates if the annotation is a markup annotation ##### Returns `boolean` *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *** ### isMoveable #### Get Signature > **get** `abstract` **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *** ### isResizable #### Get Signature > **get** `abstract` **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *** ### isRotatable #### Get Signature > **get** `abstract` **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *** ### isSelectable #### Get Signature > **get** `abstract` **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *** ### isWidgetAnnotation #### Get Signature > **get** `abstract` **isWidgetAnnotation**(): `boolean` Indicates if the annotation is a widget annotation ##### Returns `boolean` *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationLockedState) # *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The page to set as the annotation's page. # *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) # *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/AnnotationType) ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Implementation of `Disposable.dispose` --- ## Interface: AnnotationOptions Base options for all annotations ## Extended by - [`NoteAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/NoteAnnotationOptions) - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties --- ## Interface: Cloneable\ # Interface: Cloneable\ Represents an object that can be cloned to create a deep copy. ## Type Parameters ### T `T` The type of the object that the clone method returns. ## Methods ### clone() > **clone**(): `T` Creates a deep copy of the object. #### Returns `T` A new instance that is a deep copy of the original object. --- ## Interface: CustomStampAnnotationOptions **`Experimental`** An interface specific to Custom stamp annotations, defining custom content used for creating the annotation. ## Properties ### content > **content**: `PdfContent` **`Experimental`** *** ### subtype > **subtype**: [`Custom`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype#custom) **`Experimental`** --- ## Interface: CustomTextStampAnnotationOptions An interface specific to custom text stamp annotations, defining the text and color. ## Properties ### color > **color**: [`StampColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampColor) *** ### subtype > **subtype**: [`CustomText`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype#customtext) *** ### text > **text**: `string` --- ## Interface: Destination ## Properties ### bottom? > `optional` **bottom**: `number` *** ### centering? > `optional` **centering**: `boolean` *** ### destinationType > **destinationType**: [`DestinationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/DestinationType) *** ### fitContent? > `optional` **fitContent**: `boolean` *** ### left? > `optional` **left**: `number` *** ### pageNumber > **pageNumber**: `number` *** ### rectangle? > `optional` **rectangle**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> *** ### right? > `optional` **right**: `number` *** ### top? > `optional` **top**: `number` *** ### zoom? > `optional` **zoom**: `number` --- ## Interface: Disposable Disposable defines a contract for objects that require explicit cleanup or resource release when they are no longer needed. Classes implementing this interface should provide a `dispose` method to perform the necessary cleanup. ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Returns `void` --- ## Interface: Document Groups all the API actions related to document handling. ## Extends - [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler)\<[`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap)\> ## Properties ### addAnnotation() > **addAnnotation**: (`annotation`) => `Promise`\<`void`\> Adds an annotation to the document. #### Parameters ##### annotation The annotation(s) to add. [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) | [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation)[] #### Returns `Promise`\<`void`\> A promise that resolves when the annotation (or annotations) have been added. #### Throws Error if no document is loaded or if the annotation is invalid. #### Example ```ts import { NoteAnnotation, Point, PdfPoint } from '@pdftools/pdf-web-viewer'; const page = viewer.document.getPage(1); const annotation = new NoteAnnotation({ page, topLeft: new Point(100, 100) as PdfPoint, content: 'My note', }); await viewer.document.addAnnotation(annotation); ``` *** ### deleteAnnotation() > **deleteAnnotation**: (`annotation`) => `Promise`\<`void`\> Deletes the specified annotation from the document. #### Parameters ##### annotation The annotation(s) to be deleted. [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) | [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation)[] #### Returns `Promise`\<`void`\> A promise that resolves when the annotation (or annotations) are deleted. #### Throws Error if no document is loaded or if the annotation is invalid. #### Example ```ts await viewer.document.deleteAnnotation(annotation); ``` *** ### download() > **download**: (`fileName`, `options?`) => `Promise`\<`void`\> Downloads the current document. #### Parameters ##### fileName `string` The name of the file to be downloaded (default is 'download.pdf'). ##### options? [`DocumentSaveOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentSaveOptions) Document save options #### Returns `Promise`\<`void`\> A promise that resolves when the document is downloaded. #### Example ```ts await viewer.document.download(); ``` *** ### getAnnotations() > **getAnnotations**: () => `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation)[]\> Retrieves all annotations present in the current document. #### Returns `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation)[]\> A promise that resolves to an array of annotations. #### Example ```ts const annotations = await viewer.document.getAnnotations(); ``` *** ### getPage() > **getPage**: (`pageNumber`) => [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Retrieves a page from the document by its page number. #### Parameters ##### pageNumber `number` The page number to retrieve (1-based index). #### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) The `Page` object. #### Throws Error if no document is loaded or if the page number is invalid. #### Example ```ts const page = viewer.document.getPage(1); ``` *** ### getThumbnail() > **getThumbnail**: (`pageNumber`, `options?`) => `Promise`\<`HTMLImageElement`\> Retrieves a thumbnail image for a specific page in the document. #### Parameters ##### pageNumber `number` The page number for which to retrieve the thumbnail image (1-based index). ##### options? [`ThumbnailOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/ThumbnailOptions) Options for thumbnail generation including dimensions and format. #### Returns `Promise`\<`HTMLImageElement`\> A promise that resolves to the thumbnail image for the specified page. #### Example ```ts const thumbnail = await viewer.document.getThumbnail(1, { width: 100, height: 100 }); const defaultThumbnail = await viewer.document.getThumbnail(1); // Uses default options const jpegThumbnail = await viewer.document.getThumbnail(1, { format: 'jpeg', quality: 0.8 }); ``` *** ### getThumbnails() > **getThumbnails**: (`options?`) => `Promise`\<`HTMLImageElement`[]\> Retrieves thumbnail images for all pages in the document. Supports progressive rendering by using the `onThumbnail` callback and cancellation through `signal`. #### Parameters ##### options? [`ThumbnailOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/ThumbnailOptions) Options for thumbnail generation including dimensions, format, and optional `onThumbnail` callback for progressive rendering and `signal` for cancellation. #### Returns `Promise`\<`HTMLImageElement`[]\> A promise that resolves to an array of thumbnail images. #### Example ```ts // Basic usage const thumbnails = await viewer.document.getThumbnails({ width: 100, height: 100 }); // Progressive rendering with callback const abortController = new AbortController(); await viewer.document.getThumbnails({ width: 145, height: 204, signal: abortController.signal, onThumbnail: (thumbnail, pageNumber) => { container.appendChild(thumbnail); }, }); ``` *** ### open() > **open**: (`inputDocument`) => `Promise`\<`void`\> Opens a document in the PDF viewer. #### Parameters ##### inputDocument The input document to be opened, either as a `File` object or a `URI` string. [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputFile) | [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputUri) #### Returns `Promise`\<`void`\> A promise that resolves when the document is opened. #### Example ```ts await viewer.document.open({ uri: 'https://example.com/sample.pdf' }); ``` *** ### print() > **print**: (`options?`) => `Promise`\<`void`\> Prints the current document. #### Parameters ##### options? [`DocumentPrintOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentPrintOptions) Document print options. #### Returns `Promise`\<`void`\> A promise that resolves when the print dialog is closed. #### Example ```ts await viewer.document.print({ pageNumbers: [1, 2], dpi: 300 }); ``` *** ### save() > **save**: (`options?`) => `Promise`\<`Blob`\> Saves the current document. #### Parameters ##### options? [`DocumentSaveOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentSaveOptions) Document save options #### Returns `Promise`\<`Blob`\> A promise that resolves to a Blob representing the saved document. #### Example ```ts await viewer.document.save(); ``` *** ### updateAnnotation() > **updateAnnotation**: (`annotation`) => `Promise`\<`void`\> Updates the specified annotation in the document. #### Parameters ##### annotation The annotation(s) to be updated. [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) | [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation)[] #### Returns `Promise`\<`void`\> A promise that resolves when the annotation (or annotations) are updated. #### Throws Error if no document is loaded or if the annotation is invalid. #### Example ```ts await viewer.document.updateAnnotation(annotation); ``` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`eventName`, `callback`): `void` Adds an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap) #### Parameters ##### eventName `K` The name of the event to listen for. ##### callback [`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap)\[`K`\] The callback function to execute when the event is triggered. *Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#addeventlistener)* *** ### getCurrentPageNumber() > **getCurrentPageNumber**(): `number` Gets the current page number. #### Returns `number` The current page number. #### Example ```ts const currentPage = viewer.document.getCurrentPageNumber(); console.log('Current Page Number:', currentPage); ``` *** ### getPageCount() > **getPageCount**(): `number` Gets the total number of pages in the document. #### Returns `number` The total number of pages. #### Example ```ts const pageCount = viewer.document.getPageCount(); console.log('Total Pages:', pageCount); ``` *** ### removeEventListener() > **removeEventListener**\<`K`\>(`eventName`, `callback`): `void` Removes an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap) #### Parameters ##### eventName `K` The name of the event to stop listening for. ##### callback [`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentEventMap)\[`K`\] The callback function to remove. #### Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#removeeventlistener) --- ## Interface: DocumentSaveOptions Options for configuring the document save behavior. ## Properties ### saveAsFdf? > `optional` **saveAsFdf**: `boolean` Indicates whether to save the document in FDF format, which includes only the form data and annotations. #### Default Value `false` *** ### saveOriginal? > `optional` **saveOriginal**: `boolean` Indicates whether to save the original input document, discarding any interactive changes. When set to true, it bypasses the regular save process, avoiding any automatic repairs or modifications. #### Default Value `false` *** ### shouldApplyRedactions? > `optional` **shouldApplyRedactions**: `boolean` Indicates whether to apply redactions to the document when saving. #### Default Value `false` --- ## Interface: DocumentView Groups all the API actions related to the document view. ## Extends - [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler)\<[`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap)\> ## Properties ### goToDestination() > **goToDestination**: (`destination`) => `void` Navigates to a specific destination in the document. #### Parameters ##### destination [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Destination) The destination to navigate to. #### Example ```ts viewer.documentView.goToDestination(destination); ``` *** ### goToPage() > **goToPage**: (`pageNumber`) => `void` Navigates to a specific page in the document. #### Parameters ##### pageNumber `number` The page number to navigate to. #### Example ```ts viewer.documentView.goToPage(5); ``` *** ### nextPage() > **nextPage**: () => `void` Navigates to the next page in the document. #### Example ```ts viewer.documentView.nextPage(); ``` *** ### previousPage() > **previousPage**: () => `void` Navigates to the previous page in the document. #### Example ```ts viewer.documentView.previousPage(); ``` *** ### rotate() > **rotate**: (`newRotation`) => `void` Rotates the document view. #### Parameters ##### newRotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The new rotation value. #### Example ```ts viewer.documentView.rotate(90); ``` *** ### setFitMode() > **setFitMode**: (`fitMode`) => `void` Sets the fit mode of the PDF viewer. #### Parameters ##### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) The fit mode to set. #### Example ```ts viewer.documentView.setFitMode(FitMode.FitWidth); ``` *** ### setPageMode() > **setPageMode**: (`pageMode`) => `void` Sets the page mode of the PDF viewer. #### Parameters ##### pageMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) The page mode to set. #### Example ```ts viewer.documentView.setPageMode(PageLayoutMode.SinglePage); ``` *** ### setZoom() > **setZoom**: (`zoom`) => `void` Sets the zoom level of the PDF viewer. #### Parameters ##### zoom `number` The zoom level to set. #### Example ```ts viewer.documentView.setZoom(1.5); ``` *** ### zoomIn() > **zoomIn**: () => `void` Zooms in the document view. #### Example ```ts viewer.documentView.zoomIn(); ``` *** ### zoomOut() > **zoomOut**: () => `void` Zooms out the document view. #### Example ```ts viewer.documentView.zoomOut(); ``` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`eventName`, `callback`): `void` Adds an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap) #### Parameters ##### eventName `K` The name of the event to listen for. ##### callback [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap)\[`K`\] The callback function to execute when the event is triggered. *Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#addeventlistener)* *** ### getZoom() > **getZoom**(): `number` Gets the current zoom level of the document view. #### Returns `number` The current zoom level. #### Example ```ts const currentZoom = viewer.documentView.getZoom(); console.log('Current Zoom Level:', currentZoom); ``` *** ### removeEventListener() > **removeEventListener**\<`K`\>(`eventName`, `callback`): `void` Removes an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap) #### Parameters ##### eventName `K` The name of the event to stop listening for. ##### callback [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewEventMap)\[`K`\] The callback function to remove. #### Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#removeeventlistener) --- ## Interface: DrawingAnnotationOptions Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) ## Extended by - [`LineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/LineAnnotationOptions) - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) annotation stroke *** ### subject? > `optional` **subject**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: EllipseAnnotationOptions ## Extends - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#blendmode)* *** ### borderEffect? > `optional` **borderEffect**: [`BorderEffect`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BorderEffect) *** ### borderIntensity? > `optional` **borderIntensity**: `number` *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill**: `string` annotation fill *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`fill`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#fill)* *** ### fillColor? > `optional` **fillColor**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) *** ### lineColor? > `optional` **lineColor**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) *** ### lineWidth? > `optional` **lineWidth**: `number` *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) annotation stroke *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#stroke)* *** ### subject? > `optional` **subject**: `string` #### Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#subject) --- ## Interface: EventHandler\ # Interface: EventHandler\ Base interface for components with event handling capabilities. ## Extended by - [`PdfToolsViewer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PdfToolsViewer) - [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Document) - [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentView) - [`Plugins`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugins) ## Type Parameters ### TEventMap `TEventMap` *extends* `Record`\<`string`, (...`args`) => `any`\> A record mapping event names to their callback signatures. ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`eventName`, `callback`): `void` Adds an event listener for a specified event. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` #### Parameters ##### eventName `K` The name of the event to listen for. ##### callback `TEventMap`\[`K`\] The callback function to execute when the event is triggered. *** ### removeEventListener() > **removeEventListener**\<`K`\>(`eventName`, `callback`): `void` Removes an event listener for a specified event. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` #### Parameters ##### eventName `K` The name of the event to stop listening for. ##### callback `TEventMap`\[`K`\] The callback function to remove. #### Returns `void` --- ## Interface: FreeTextAnnotationOptions Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#author)* *** ### backgroundColor? > `optional` **backgroundColor**: `string` *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### rotation? > `optional` **rotation**: `number` *** ### subject? > `optional` **subject**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: ImageStampAnnotationOptions An interface specific to image stamp annotations, defining the registered image used for creating the annotation. ## Properties ### image > **image**: `PdfImage` *** ### subtype > **subtype**: [`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype#image) --- ## Interface: InputFile A file that can be opened on a `Blob`, `File` or `Uint8Array`. ## Extends - `InputDocument` ## Properties ### annotationTag? > `optional` **annotationTag**: `string` Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF). *Inherited from `InputDocument.annotationTag`* *** ### autoRepairDisabled? > `optional` **autoRepairDisabled**: `boolean` A boolean property that controls whether automatic repairs on PDF files are disabled. Setting this property to `true` prevents the application from performing any automatic repair operations on PDF files, which could alter the file's structure and potentially invalidate digital signatures within the document. #### Default Value `false` *Inherited from `InputDocument.autoRepairDisabled`* *** ### data > **data**: `Uint8Array`\<`ArrayBufferLike`\> \| `Blob` \| `File` A `Blob`, `File` or `Uint8Array` containing the file. *** ### fileName? > `optional` **fileName**: `string` Name for the input document *Inherited from `InputDocument.fileName`* *** ### password? > `optional` **password**: `string` The password used for opening the PdfDocument. #### Inherited from `InputDocument.password` --- ## Interface: InputUri A file that can be opened on a text-uri. ## Extends - `InputDocument` ## Properties ### annotationTag? > `optional` **annotationTag**: `string` Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF). *Inherited from `InputDocument.annotationTag`* *** ### autoRepairDisabled? > `optional` **autoRepairDisabled**: `boolean` A boolean property that controls whether automatic repairs on PDF files are disabled. Setting this property to `true` prevents the application from performing any automatic repair operations on PDF files, which could alter the file's structure and potentially invalidate digital signatures within the document. #### Default Value `false` *Inherited from `InputDocument.autoRepairDisabled`* *** ### fileName? > `optional` **fileName**: `string` Name for the input document *Inherited from `InputDocument.fileName`* *** ### httpOptions? > `optional` **httpOptions**: `HttpOptions` Options that are applied to a HTTP request. *** ### password? > `optional` **password**: `string` The password used for opening the PdfDocument. *Inherited from `InputDocument.password`* *** ### uri > **uri**: `string` The uri where the file can be loaded from. --- ## Interface: LineAnnotationOptions Base options for all annotations ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### color? > `optional` **color**: [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbaColor) *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#datemodified)* *** ### endPoint? > `optional` **endPoint**: [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) *** ### lineEndingAtEnd? > `optional` **lineEndingAtEnd**: [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) *** ### lineEndingAtStart? > `optional` **lineEndingAtStart**: [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/LineEnding) *** ### lineWidth? > `optional` **lineWidth**: `number` *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### startPoint? > `optional` **startPoint**: [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) *** ### stroke? > `optional` **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#stroke)* *** ### subject? > `optional` **subject**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: MarkupAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions) ## Extended by - [`FreeTextAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/FreeTextAnnotationOptions) - [`TextMarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextMarkupAnnotationOptions) - [`StampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/StampAnnotationOptions) - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject**: `string` --- ## Interface: NoteAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#datemodified)* *** ### fillColor? > `optional` **fillColor**: [`NoteAnnotationColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/NoteAnnotationColor) Pdf.Annotations.NoteAnnotation.fillColor #### Default Value `"#FFECB3"` *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/AnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject**: `string` *** ### topLeft > **topLeft**: [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) Pdf.Annotations.NoteAnnotation.topLeft #### Default Value `new Point(0, 0) as PdfPoint` --- ## Interface: Page A single page in a Pdf document. ## Extends - `EventEmitter`\<`PageEventMap`\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Disposable) ## Accessors ### document #### Get Signature > **get** **document**(): `Document` the pdf document to which the page belongs ##### Returns `Document` *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` indicates if the page or its content has been changed since the document was last saved ##### Returns `boolean` *** ### height #### Get Signature > **get** **height**(): `number` Height of the page in PDF coordinates. This represents the height of the page, taking into account the rotation. ##### Returns `number` *** ### isDeleted #### Get Signature > **get** **isDeleted**(): `boolean` indicates whether the page was deleted ##### Returns `boolean` *** ### originalHeight #### Get Signature > **get** **originalHeight**(): `number` Original height of the page in PDF coordinates. This represents the original height of the page without considering any rotation. ##### Returns `number` *** ### originalWidth #### Get Signature > **get** **originalWidth**(): `number` Original width of the page in PDF coordinates. This represents the original width of the page without considering any rotation. ##### Returns `number` *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` page number ##### Returns `number` *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) Rotation of the page ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) *** ### width #### Get Signature > **get** **width**(): `number` Width of the page in PDF coordinates. This represents the width of the page, taking into account the rotation. ##### Returns `number` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from `EventEmitter.addEventListener`* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<`PageEventMap`\[`K`\]\> The data associated with the event. *Inherited from `EventEmitter.dispatchEvent`* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of `Disposable.dispose`* *** ### getTextFragments() > **getTextFragments**(): [`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextFragment)[] Gets text fragments of a `Pdf.Page`. #### Returns [`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextFragment)[] A Promise that resolves to an Array containing the text fragments. #### Throws `Pdf.NotLoadedError` if text fragments are not loaded yet. *** ### loadTextFragments() > **loadTextFragments**(): `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextFragment)[]\> Loads text fragments of a `Pdf.Page`. #### Returns `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/TextFragment)[]\> A Promise that resolves to an Array containing the text fragments. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from `EventEmitter.removeAllListeners`* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Inherited from `EventEmitter.removeEventListener`* *** ### render() > **render**(`renderOptions`): `Promise`\<`Blob`\> Render the given page #### Parameters ##### renderOptions [`PageRenderOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/PageRenderOptions) Options for rendering the page #### Returns `Promise`\<`Blob`\> Blob containing the image data *** ### rotate() > **rotate**(`direction`, `degree?`): `void` Rotates the page in the specified direction by the specified degree The rotation can only be done in steps of 90 degrees or a multiple thereof #### Parameters ##### direction `RotationDirection` clockwise or counter-clockwise ##### degree? `number` rotation in degrees in multiples of 90 *** ### transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral() > **transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Converts a quadrilateral from document view coordinates to PDF coordinates. This function transforms a `Quadrilateral`, which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen, to a `Quadrilateral`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> The `Quadrilateral` object representing the quadrilateral in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> A new instance of `Quadrilateral` representing the converted coordinates in PDF units. *** ### transformDocumentViewPointRectangleToPdfPointRectangle() > **transformDocumentViewPointRectangleToPdfPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Converts a rectangle from document view coordinates to PDF coordinates. This function transforms a `Rectangle`, which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen, to a `Rectangle`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> The `Rectangle` object representing the rectangle in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> A new instance of `Rectangle` representing the converted coordinates in PDF units. *** ### transformDocumentViewPointToPdfPoint() > **transformDocumentViewPointToPdfPoint**(`point`, `width`, `height`, `rotation`): [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) Converts a point from document view coordinates to PDF coordinates. This function transforms a `DocumentViewPoint`, which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen, to a `PdfPoint`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### point [`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint) The `DocumentViewPoint` object representing the point in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) A new instance of `PdfPoint` representing the converted coordinates in PDF units. *** ### transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral() > **transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> Converts a quadrilateral from PDF coordinates to document view coordinates. This function transforms a `Quadrilateral`, which is measured in PDF units, to a `Quadrilateral`, which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> The `Quadrilateral` object representing the quadrilateral in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> A new instance of `Quadrilateral` representing the converted coordinates in document view units. *** ### transformPdfPointRectangleToDocumentViewPointRectangle() > **transformPdfPointRectangleToDocumentViewPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> Converts a rectangle from PDF coordinates to document view coordinates. This function transforms a `Rectangle`, which is measured in PDF units, to a `Rectangle`, which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> The `Rectangle` object representing the rectangle in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint)\> A new instance of `Rectangle` representing the converted coordinates in document view units. *** ### transformPdfPointToDocumentViewPoint() > **transformPdfPointToDocumentViewPoint**(`point`, `width`, `height`, `rotation`): [`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint) Converts a point from PDF coordinates to document view coordinates. This function transforms a `PdfPoint`, which is measured in PDF units, to a `DocumentViewPoint`, which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### point [`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint) The `PdfPoint` object representing the point in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The rotation of the page. #### Returns [`DocumentViewPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/DocumentViewPoint) A new instance of `DocumentViewPoint` representing the converted coordinates in document view units. --- ## Interface: PdfStampAnnotationOptions An interface specific to PDF stamp annotations, defining the registered PDF content (PDF page) used for creating the annotation. ## Properties ### pdfStamp > **pdfStamp**: `PdfContent` *** ### subtype > **subtype**: [`Pdf`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype#pdf) --- ## Interface: PdfToolsViewer API for interacting with the PDF Viewer SDK, exposing core functionalities for document interaction, event handling, and UI management. ## Extends - [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler)\<[`EventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap)\> ## Properties ### dispose() > **dispose**: () => `void` Disposes of the PDF Viewer instance, freeing up resources. #### Example ```ts viewer.dispose(); ``` *** ### document > **document**: [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Document) Groups all the document-related API actions. *** ### documentView > **documentView**: [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DocumentView) Groups all the documentView-related API actions. *** ### getUser() > **getUser**: () => `string` Gets the current user. #### Returns `string` The user identifier, or null if no user is set. *** ### hideComponents() > **hideComponents**: (`paths`) => `void` Hides specified UI components in the Viewer. #### Parameters ##### paths List of components path to hide. `string`[] | `string`[][] #### Example ```ts viewer.hideComponents([['pdftools-toolbar', 'pdftools-hamburger-menu']]); ``` *** ### initialize() > **initialize**: (`config`, `container`) => `Promise`\<`void`\> Initializes the PDF Viewer within a specified container element. #### Parameters ##### config [`ViewerConfig`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/ViewerConfig) The configuration options for initializing the viewer. ##### container `HTMLElement` The HTML element to contain the viewer. #### Returns `Promise`\<`void`\> A promise that resolves when the viewer is initialized. #### Example ```ts await viewer.initialize(config, document.getElementById('viewer-container')); ``` *** ### overrideButtonBehavior() > **overrideButtonBehavior**: (`path`, `eventName`, `callback`) => `void` Overrides the behavior of a specific button. #### Parameters ##### path The selector path to the button component. `string` | `string`[] ##### eventName `"click"` The name of the event to listen for. ##### callback () => `void` The callback function to execute when the event is triggered. #### Example ```ts viewer.overrideButtonBehavior(['pdftools-toolbar', '#pdftools-save-document-btn']); ``` *** ### plugins > **plugins**: [`Plugins`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugins) Groups all the plugins-related API actions. Plugins let users extend the viewer with their own interactive layers and behaviors. *** ### setUser() > **setUser**: (`user`) => `void` Sets the user. #### Parameters ##### user `string` The user identifier. *** ### showComponents() > **showComponents**: (`paths`) => `void` Shows specified UI components in the Viewer. #### Parameters ##### paths List of components path to show. `string`[] | `string`[][] #### Example ```ts viewer.showComponents([['pdftools-toolbar', 'pdftools-hamburger-menu']]); ``` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`eventName`, `callback`): `void` Adds an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`EventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap) #### Parameters ##### eventName `K` The name of the event to listen for. ##### callback [`EventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap)\[`K`\] The callback function to execute when the event is triggered. *Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#addeventlistener)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`eventName`, `callback`): `void` Removes an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`EventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap) #### Parameters ##### eventName `K` The name of the event to stop listening for. ##### callback [`EventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/EventMap)\[`K`\] The callback function to remove. #### Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#removeeventlistener) --- ## Interface: Plugin Represents a plugin that can be registered, activated, and deactivated. ## Properties ### documentView > **documentView**: [`UIDocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/UIDocumentView) The document view associated with the plugin. *** ### id > **id**: `string` Unique identifier for the plugin. ## Methods ### activate() > **activate**(): `void` Activates the plugin. *** ### deactivate() > **deactivate**(): `void` Deactivates the plugin. #### Returns `void` --- ## Interface: Plugins Groups all the API actions related to plugins in the Viewer. Plugins allow users to extend the viewer's functionality with their own interactive layers and behaviors. ## Extends - [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler)\<[`PluginsEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap)\> ## Properties ### activate() > **activate**: (`pluginId`) => `void` Activates a plugin by its ID. This deactivates all other plugins and calls the plugin's `activate()` method. #### Parameters ##### pluginId `string` The unique ID of the plugin to activate. #### Throws If the plugin with the given ID does not exist. #### Example ```ts viewer.plugins.activate('my-custom-plugin'); ``` *** ### deactivate() > **deactivate**: (`pluginId`) => `void` Deactivates a plugin by its ID. This calls the plugin's `deactivate()` method. #### Parameters ##### pluginId `string` The unique ID of the plugin to deactivate. #### Throws If the plugin with the given ID does not exist. #### Example ```ts viewer.plugins.deactivate('my-custom-plugin'); ``` *** ### deregister() > **deregister**: (`pluginId`) => `void` Deregisters a plugin from the viewer. This deactivates the plugin if it's currently active and removes it from the plugin manager. #### Parameters ##### pluginId `string` The unique ID of the plugin to deregister. #### Throws If the plugin with the given ID does not exist. #### Example ```ts viewer.plugins.deregister('my-custom-plugin'); ``` *** ### get() > **get**: (`pluginId`) => [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugin) Gets a plugin by its ID. #### Parameters ##### pluginId `string` The unique ID of the plugin to retrieve. #### Returns [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugin) - The plugin instance, or undefined if not found. #### Example ```ts const plugin = viewer.plugins.get('my-custom-plugin'); ``` *** ### getActive() > **getActive**: () => `string` Gets the ID of the currently active plugin. #### Returns `string` The unique ID of the active plugin, or null if no plugin is active. #### Example ```ts const activePluginId = viewer.plugins.getActive(); ``` *** ### isActive() > **isActive**: (`pluginId`) => `boolean` Checks if a plugin is currently active. #### Parameters ##### pluginId `string` The unique ID of the plugin to check. #### Returns `boolean` The value is `true` if the plugin is active, `false` otherwise. #### Example ```ts const isActive = viewer.plugins.isActive('my-custom-plugin'); ``` *** ### register() > **register**: (`plugin`) => `void` Registers a plugin with the viewer. The plugin must implement the `Plugin` interface with a unique ID, `documentView` reference, and `activate` or `deactivate` methods. #### Parameters ##### plugin [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Plugin) The plugin to register. Must implement the `Plugin` interface. #### Throws If a plugin with the same ID is already registered. #### Example ```ts viewer.plugins.register({ id: 'my-custom-plugin', documentView: myDocumentViewInstance, activate: () => { console.log('Plugin activated'); }, deactivate: () => { console.log('Plugin deactivated'); } }); ``` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`eventName`, `callback`): `void` Adds an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`PluginsEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap) #### Parameters ##### eventName `K` The name of the event to listen for. ##### callback [`PluginsEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap)\[`K`\] The callback function to execute when the event is triggered. *Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#addeventlistener)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`eventName`, `callback`): `void` Removes an event listener for a specified event. #### Type Parameters ##### K `K` *extends* keyof [`PluginsEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap) #### Parameters ##### eventName `K` The name of the event to stop listening for. ##### callback [`PluginsEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PluginsEventMap)\[`K`\] The callback function to remove. #### Inherited from [`EventHandler`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EventHandler#removeeventlistener) --- ## Interface: PredefinedTextStampAnnotationOptions An interface specific to predefined text stamp annotations, defining the predefined text stamp type. ## Properties ### predefinedTextStampType > **predefinedTextStampType**: [`PredefinedTextStampType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PredefinedTextStampType) *** ### subtype > **subtype**: [`PredefinedText`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/StampAnnotationSubtype#predefinedtext) --- ## Interface: RectangleAnnotationOptions ## Extends - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill**: `string` annotation fill *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`fill`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#fill)* *** ### fillColor? > `optional` **fillColor**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) *** ### lineColor? > `optional` **lineColor**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) *** ### lineWidth? > `optional` **lineWidth**: `number` *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) annotation stroke *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#stroke)* *** ### subject? > `optional` **subject**: `string` #### Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ShapeAnnotationOptions#subject) --- ## Interface: ShapeAnnotationOptions ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions) ## Extended by - [`RectangleAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/RectangleAnnotationOptions) - [`EllipseAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/EllipseAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill**: `string` annotation fill *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#stroke)* *** ### subject? > `optional` **subject**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: StampAnnotationOptions Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#content)* *** ### data > **data**: [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/StampData) An object representing the stamp annotation data, which depends on the subtype. *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: TextFragment Represents a text fragment within a document, containing information about its position, content, and layout. ## Properties ### glyphOffsets > **glyphOffsets**: `number`[] An array of glyph offsets representing the offset of each character within the text fragment. Glyph offsets are used for precise positioning and layout purposes. *** ### pageNumber > **pageNumber**: `number` The page number where the text fragment is located within the document. *** ### quadrilateral > **quadrilateral**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> A quadrilateral representing the bounding box or area occupied by the text fragment. This quadrilateral defines the spatial extent of the text fragment on the page. *** ### text > **text**: `string` The actual textual content of the text fragment. --- ## Interface: TextMarkupAnnotationOptions Interface representing options for text markup annotations. This interface extends [MarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) and provides additional properties specific to text markup annotations, such as the marked area, annotation subtype, and fill color. ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Rectangle)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\> Pdf.Annotations.Annotation.boundingBox #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content**: `string` Pdf.Annotations.Annotation.content #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified**: `Date` Pdf.Annotations.Annotation.dateModified *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#datemodified)* *** ### fillColor? > `optional` **fillColor**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/RgbColor) The color used to fill the marked-up area. *** ### opacity? > `optional` **opacity**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Page) Pdf.Annotations.Annotation.page *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData**: `string` Pdf.Annotations.Annotation.privateData #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/AnnotationRenderProperties) Pdf.Annotations.AnnotationRenderProperties *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/MarkupAnnotationOptions#subject)* *** ### subtype? > `optional` **subtype**: [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/TextMarkupType) Specifies the subtype of text markup annotation. Determines how the text is visually marked, such as highlight, underline, strikethrough, squiggly, or redact. *** ### textMarkupArea? > `optional` **textMarkupArea**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Quadrilateral)\<[`PdfPoint`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/PdfPoint)\>[] An array of quadrilateral regions defining the marked-up text area. Each quadrilateral represents a portion of the text affected by the annotation. --- ## Interface: UIDocumentView Class for managing the presentation and interaction with a PDF document within a container element. ## Extends - `EventEmitter`\<`DocumentViewEventMap`\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Disposable) ## Accessors ### accessibilityLayerEnabled #### Get Signature > **get** **accessibilityLayerEnabled**(): `boolean` Enables or disables the accessibility layer for the document view. When enabled, the accessibility layer provides support for screen readers and other accessibility tools by creating an invisible HTML structure that aligns with the text fragments on the page. ##### Returns `boolean` #### Set Signature > **set** **accessibilityLayerEnabled**(`v`): `void` ##### Parameters ###### v `boolean` # *** ### currentPageNumber #### Get Signature > **get** **currentPageNumber**(): `number` Gets or sets the currently most visible page. ##### Returns `number` The number of the page which covers the largest area on the viewport, or `null` if the document view is not initialized. If multiple pages cover the same amount of space, the one with the smaller page number is returned. #### Set Signature > **set** **currentPageNumber**(`pageNumber`): `void` ##### Parameters ###### pageNumber `number` # *** ### devicePixelRatio #### Get Signature > **get** **devicePixelRatio**(): `number` Gets the device pixel ratio used for rendering. ##### Returns `number` *** ### firstVisiblePageNumber #### Get Signature > **get** **firstVisiblePageNumber**(): `number` Gets the page number of the first visible page in the document view. ##### Returns `number` The page number of the first visible page, or `null` if the document view is not initialized. *** ### fitMode #### Get Signature > **get** **fitMode**(): [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) **`Experimental`** Gets or sets the fit mode for the document view. ##### Returns [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) #### Set Signature > **set** **fitMode**(`fitMode`): `void` ##### Parameters ###### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) # *** ### lastVisiblePageNumber #### Get Signature > **get** **lastVisiblePageNumber**(): `number` Gets the page number of the last visible page in the document view. ##### Returns `number` The page number of the last visible page, or `null` if the document view is not initialized. *** ### pageLayoutMode #### Get Signature > **get** **pageLayoutMode**(): [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) **`Experimental`** Gets or sets the page layout mode for the document view. ##### Returns [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) #### Set Signature > **set** **pageLayoutMode**(`pageLayoutMode`): `void` ##### Parameters ###### pageLayoutMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) # *** ### pdfDocument #### Get Signature > **get** **pdfDocument**(): `Document` Gets `Pdf.Document` attached to the `DocumentView`. ##### Returns `Document` *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) **`Experimental`** Gets or sets the rotation for the document view. ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) #### Set Signature > **set** **rotation**(`rotation`): `void` ##### Parameters ###### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) # *** ### scrollAllowance #### Get Signature > **get** **scrollAllowance**(): `ScrollAllowance` Get the current scroll allowances ##### Returns `ScrollAllowance` *** ### scrollContainer #### Get Signature > **get** **scrollContainer**(): `HTMLDivElement` Retrieves the scroll container element. The scroll container holds the individual PDF pages within the viewport. This element manages the scrolling behavior and allows navigation through different pages of the PDF document. ##### Returns `HTMLDivElement` The scroll container element. *** ### slidingWindow #### Get Signature > **get** **slidingWindow**(): `Map`\<`number`, `DocumentViewPage`\> Gets pages in sliding window. ##### Returns `Map`\<`number`, `DocumentViewPage`\> *** ### viewport #### Get Signature > **get** **viewport**(): `HTMLDivElement` Retrieves the viewport element. The viewport represents the entire document view of the PDF. It acts as the main container that defines the visible area of the PDF document. ##### Returns `HTMLDivElement` The viewport container element. *** ### zoom #### Get Signature > **get** **zoom**(): `number` Gets or sets the currently used zoom factor as a floating-point number. 1 corresponds to a zoom level of 100%. ##### Returns `number` Zoom level or null if the document view is not initialized. #### Set Signature > **set** **zoom**(`zoom`): `void` ##### Parameters ###### zoom `number` # *** ### zoomLevels #### Get Signature > **get** **zoomLevels**(): `number`[] Gets or sets the array of zoom levels available for the document view. ##### Returns `number`[] #### Set Signature > **set** **zoomLevels**(`zoomLevels`): `void` ##### Parameters ###### zoomLevels `number`[] # ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* keyof `DocumentViewEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from `EventEmitter.addEventListener`* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* keyof `DocumentViewEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<`DocumentViewEventMap`\[`K`\]\> The data associated with the event. *Inherited from `EventEmitter.dispatchEvent`* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of `Disposable.dispose`* *** ### goToDestination() > **goToDestination**(`destination`): `void` Navigates to the specified destination in the document view. #### Parameters ##### destination [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Destination) The destination to navigate to. *** ### goToPage() > **goToPage**(`pageNumber`): `any` Navigates to the specified page in the document view. #### Parameters ##### pageNumber `number` The page number to navigate to. #### Returns `any` *** ### initialize() > **initialize**(`pdfDocument`): `void` Initializes the document view. #### Parameters ##### pdfDocument `Document` The PDF document which will be displayed inside the document view. *** ### nextPage() > **nextPage**(): `any` Navigates to the next page in the document view. #### Returns `any` *** ### previousPage() > **previousPage**(): `any` Navigates to the previous page in the document view. #### Returns `any` *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* keyof `DocumentViewEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from `EventEmitter.removeAllListeners`* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* keyof `DocumentViewEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from `EventEmitter.removeEventListener` --- ## Type Alias: Cursor > **Cursor** = `"auto"` \| `"crosshair"` \| `"pointer"` \| `"wait"` --- ## Type Alias: DocumentEventMap > **DocumentEventMap** = `object` Event map for document events. ## Properties ### annotationAdded() > **annotationAdded**: (`annotation`) => `void` Fired when an annotation is added to the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) The annotation that was added. *** ### annotationDeleted() > **annotationDeleted**: (`annotation`) => `void` Fired when an annotation is deleted from the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) The annotation that was deleted. *** ### annotationUpdated() > **annotationUpdated**: (`annotation`) => `void` Fired when an annotation is updated in the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) The annotation that was updated. *** ### opened() > **opened**: (`inputDocument`) => `void` Fired when a document is opened. #### Parameters ##### inputDocument The input document that was opened. [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputFile) | [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputUri) *** ### pageRendered() > **pageRendered**: (`pageNumber`) => `void` Fired when a page has been rendered. #### Parameters ##### pageNumber `number` The number of the page that was rendered. *** ### printCompleted() > **printCompleted**: () => `void` Fired when document printing has completed successfully. *** ### printFailed() > **printFailed**: (`error`) => `void` Fired when document printing has failed. #### Parameters ##### error `Error` The error that caused the print to fail. *** ### printStarted() > **printStarted**: () => `void` Fired when document printing has started. #### Returns `void` --- ## Type Alias: DocumentPrintOptions > **DocumentPrintOptions** = `object` Options for configuring document printing. ## Properties ### dpi? > `optional` **dpi**: `number` The print resolution in dots per inch (DPI). Higher values produce better quality but larger file sizes. *** ### includeAnnotations? > `optional` **includeAnnotations**: `boolean` Whether to include annotations in the printed document. *** ### pageNumbers? > `optional` **pageNumbers**: `number`[] Specific page numbers to print. If not specified, all pages will be printed. --- ## Type Alias: DocumentViewEventMap > **DocumentViewEventMap** = `object` Event map for document view events. ## Properties ### clicked() > **clicked**: (`pageNumber`, `point`) => `void` Fired when the document view is clicked. #### Parameters ##### pageNumber `number` The page number where the click occurred. ##### point [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) The coordinates of the click. *** ### doubleclicked() > **doubleclicked**: (`pageNumber`, `point`) => `void` Fired when the document view is double-clicked. #### Parameters ##### pageNumber `number` The page number where the double-click occurred. ##### point [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) The coordinates of the double-click. *** ### fitModeChanged() > **fitModeChanged**: (`fitMode`) => `void` Fired when the fit mode changes. #### Parameters ##### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) The new fit mode. *** ### pageChanged() > **pageChanged**: (`pageNumber`) => `void` Fired when the current page changes. #### Parameters ##### pageNumber `number` The new page number. *** ### pageModeChanged() > **pageModeChanged**: (`pageMode`) => `void` Fired when the page layout mode changes. #### Parameters ##### pageMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) The new page layout mode. *** ### rotated() > **rotated**: (`rotation`) => `void` Fired when the document view is rotated. #### Parameters ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) The new rotation value. *** ### setCursor() > **setCursor**: (`cursor`) => `void` Fired when the cursor style is changed. #### Parameters ##### cursor [`Cursor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/Cursor) The new cursor style. *** ### zoomChanged() > **zoomChanged**: (`zoom`) => `void` Fired when the zoom level changes. #### Parameters ##### zoom `number` The new zoom level. #### Returns `void` --- ## Type Alias: DocumentViewPoint > **DocumentViewPoint** = `Brand`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point), `"DocumentViewPoint"`\> Represents a point in the document view, corresponding to a PDF point that is scaled proportionally based on the rendered size of the document on screen relative to its original size in PDF units. This type aligns with HTML event coordinates emitted when interacting with the DOM, ensuring consistency between PDF rendering and user interactions. --- ## Type Alias: EventMap > **EventMap** = `object` Global event map combining all domain event maps with full event paths. Used for the main viewer's addEventListener/removeEventListener. ## Properties ### PdfTools.document.annotationAdded() > **PdfTools.document.annotationAdded**: (`annotation`) => `void` Fired when an annotation is added to the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) *** ### PdfTools.document.annotationDeleted() > **PdfTools.document.annotationDeleted**: (`annotation`) => `void` Fired when an annotation is deleted from the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) *** ### PdfTools.document.annotationUpdated() > **PdfTools.document.annotationUpdated**: (`annotation`) => `void` Fired when an annotation is updated in the document. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/Annotation) *** ### PdfTools.document.opened() > **PdfTools.document.opened**: (`inputDocument`) => `void` Fired when a document is opened. #### Parameters ##### inputDocument [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputFile) | [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputUri) *** ### PdfTools.document.pageRendered() > **PdfTools.document.pageRendered**: (`pageNumber`) => `void` Fired when a page has been rendered. #### Parameters ##### pageNumber `number` *** ### PdfTools.document.printCompleted() > **PdfTools.document.printCompleted**: () => `void` Fired when document printing has completed successfully. *** ### PdfTools.document.printFailed() > **PdfTools.document.printFailed**: (`error`) => `void` Fired when document printing has failed. #### Parameters ##### error `Error` *** ### PdfTools.document.printStarted() > **PdfTools.document.printStarted**: () => `void` Fired when document printing has started. *** ### PdfTools.documentView.clicked() > **PdfTools.documentView.clicked**: (`pageNumber`, `point`) => `void` Fired when the document view is clicked. #### Parameters ##### pageNumber `number` ##### point [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) *** ### PdfTools.documentView.doubleclicked() > **PdfTools.documentView.doubleclicked**: (`pageNumber`, `point`) => `void` Fired when the document view is double-clicked. #### Parameters ##### pageNumber `number` ##### point [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point) *** ### PdfTools.documentView.fitModeChanged() > **PdfTools.documentView.fitModeChanged**: (`fitMode`) => `void` Fired when the fit mode changes. #### Parameters ##### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/FitMode) *** ### PdfTools.documentView.pageChanged() > **PdfTools.documentView.pageChanged**: (`pageNumber`) => `void` Fired when the current page changes. #### Parameters ##### pageNumber `number` *** ### PdfTools.documentView.pageModeChanged() > **PdfTools.documentView.pageModeChanged**: (`pageMode`) => `void` Fired when the page layout mode changes. #### Parameters ##### pageMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/PageLayoutMode) *** ### PdfTools.documentView.rotated() > **PdfTools.documentView.rotated**: (`rotation`) => `void` Fired when the document view is rotated. #### Parameters ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/enumerations/Rotation) *** ### PdfTools.documentView.setCursor() > **PdfTools.documentView.setCursor**: (`cursor`) => `void` Fired when the cursor style is changed. #### Parameters ##### cursor [`Cursor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/Cursor) *** ### PdfTools.documentView.zoomChanged() > **PdfTools.documentView.zoomChanged**: (`zoom`) => `void` Fired when the zoom level changes. #### Parameters ##### zoom `number` *** ### PdfTools.plugins.activated() > **PdfTools.plugins.activated**: (`pluginId`) => `void` Fired when a plugin is activated. #### Parameters ##### pluginId `string` *** ### PdfTools.plugins.deactivated() > **PdfTools.plugins.deactivated**: (`pluginId`) => `void` Fired when a plugin is deactivated. #### Parameters ##### pluginId `string` *** ### PdfTools.plugins.deregistered() > **PdfTools.plugins.deregistered**: (`pluginId`) => `void` Fired when a plugin is deregistered. #### Parameters ##### pluginId `string` *** ### PdfTools.plugins.registered() > **PdfTools.plugins.registered**: (`pluginId`) => `void` Fired when a plugin is registered. #### Parameters ##### pluginId `string` *** ### PdfTools.viewer.initialized() > **PdfTools.viewer.initialized**: () => `void` Fired when the viewer has finished initialization. #### Returns `void` --- ## Type Alias: LicenseKey > **LicenseKey** = `` `` `` Represents a license key for the Pdftools PDF Web SDK. The license key is a string that contains the license information. --- ## Type Alias: NoteAnnotationColor > **NoteAnnotationColor** = `"#86F9AC"` \| `"#FFECB3"` \| `"#FFD6B3"` \| `"#FBB6F5"` \| `"#B6DDFB"` --- ## Type Alias: OverridableButtonEventType > **OverridableButtonEventType** = *typeof* `OVERRIDABLE_BUTTON_EVENTS`\[`number`\] Types of button events that can be overridden. --- ## Type Alias: PdfPoint > **PdfPoint** = `Brand`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/classes/Point), `"PdfPoint"`\> Represents a point in the PDF coordinate system, measured in PDF units. In this system, the origin (0, 0) is at the top-left corner of the page, with the x-axis increasing to the right and the y-axis increasing downward. This type is used to define precise locations within a PDF document. --- ## Type Alias: PluginsEventMap > **PluginsEventMap** = `object` Event map for plugin events. ## Properties ### activated() > **activated**: (`pluginId`) => `void` Fired when a plugin is activated. #### Parameters ##### pluginId `string` The unique ID of the activated plugin. *** ### deactivated() > **deactivated**: (`pluginId`) => `void` Fired when a plugin is deactivated. #### Parameters ##### pluginId `string` The unique ID of the deactivated plugin. *** ### deregistered() > **deregistered**: (`pluginId`) => `void` Fired when a plugin is deregistered. #### Parameters ##### pluginId `string` The unique ID of the deregistered plugin. *** ### registered() > **registered**: (`pluginId`) => `void` Fired when a plugin is registered. #### Parameters ##### pluginId `string` The unique ID of the registered plugin. #### Returns `void` --- ## Type Alias: StampData > **StampData** = [`PredefinedTextStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PredefinedTextStampAnnotationOptions) \| [`CustomTextStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/CustomTextStampAnnotationOptions) \| [`ImageStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/ImageStampAnnotationOptions) \| [`PdfStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/PdfStampAnnotationOptions) \| [`CustomStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/CustomStampAnnotationOptions) A type that represents stamp data, which can be one of the specific options for different subtypes. --- ## Type Alias: ThumbnailOptions > **ThumbnailOptions** = `object` Options for configuring thumbnail generation. ## Properties ### format? > `optional` **format**: `"png"` \| `"jpeg"` Image format for the thumbnail. Supported formats are 'png' and 'jpeg'. By default, thumbnails will be generated in 'png' format. *** ### height? > `optional` **height**: `number` Height of the thumbnail in pixels. By default, thumbnails will have a height of 100 pixels. *** ### onThumbnail()? > `optional` **onThumbnail**: (`thumbnail`, `pageNumber`) => `void` Callback fired for each thumbnail as it loads. Used for progressive rendering. Only applicable when using `getThumbnails()` method. #### Parameters ##### thumbnail `HTMLImageElement` ##### pageNumber `number` *** ### quality? > `optional` **quality**: `number` Quality for JPEG format. Only applies when format is 'jpeg'. Value should be between 0 and 1, where 1 is the highest quality. By default, the quality will be set to 0.92. *** ### signal? > `optional` **signal**: `AbortSignal` AbortSignal to cancel thumbnail generation. Only applicable when using `getThumbnails()` method. *** ### width? > `optional` **width**: `number` Width of the thumbnail in pixels. By default, thumbnails will have a width of 100 pixels. --- ## Type Alias: ViewerConfig > **ViewerConfig** = `object` Represents the configuration options for initializing the PDF viewer. ## Properties ### accessibilityLayerEnabled? > `optional` **accessibilityLayerEnabled**: `boolean` Whether to enable the accessibility layer. This improves accessibility for users with disabilities. *** ### customCssVars? > `optional` **customCssVars**: `Record`\<`CssVar`, `string`\> Custom CSS variables to apply to the viewer. This allows for theming and styling of the viewer components. The keys should be valid CSS variable names (e.g., `--primary-color`) and the values should be valid CSS values (e.g., `#ff0000` or `16px`). *** ### customLocalisationFile? > `optional` **customLocalisationFile**: `string` Custom localisation file URL. If provided, the viewer will load the localisation data from this file instead of using the default translations. The file should be in `JSON` format and follow the structure of the default localisation files. *** ### devicePixelRatio? > `optional` **devicePixelRatio**: `number` The device pixel ratio (DPR) setting for rendering the PDF. Higher values result in better quality but may impact performance. *** ### inputDocument? > `optional` **inputDocument**: [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputFile) \| [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/interfaces/InputUri) An optional input document to open in the viewer upon initialization. This can be either a file or a URI. If provided, the viewer will automatically load and display this document when it is initialized. *** ### lang? > `optional` **lang**: `"en"` \| `"de"` The language to use in the viewer. Supported values are `en` for English and `de` for German. If not specified, the viewer will default to English. *** ### licenseKey? > `optional` **licenseKey**: [`LicenseKey`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/viewer/type-aliases/LicenseKey) License key for the PDF viewer. This is required for the viewer to function properly. You can obtain a license key from the PDF Tools website. If you are using a trial version of the viewer, you can use the staging license key provided in the documentation, but keep in mind that it will add a watermark to the documents. *** ### licenseUrl? > `optional` **licenseUrl**: `string` URL to fetch the license key from. This is required if you are using a license key that needs to be fetched from a server. The viewer will request this URL to retrieve the license key during initialization. *** ### path? > `optional` **path**: `string` Path to the worker script. This is required for the viewer to function properly, as it uses a web worker for rendering and processing PDF documents. *** ### producerSuffix? > `optional` **producerSuffix**: `string` Suffix to append to the producer string in the PDF metadata. *** ### user? > `optional` **user**: `string` An optional user identifier to associate with the viewer session. If not specified, the viewer will use a default user identifier. *** ### zoomLevels? > `optional` **zoomLevels**: `number`[] Custom zoom levels for the viewer. This allows you to specify the zoom levels that will be available in the viewer's zoom dropdown. The values should be numbers representing the zoom percentage (e.g., `1` for 100% zoom, `1.5` for 150% zoom, `0.25` for 25% zoom). If not specified, the viewer will use default zoom levels. --- ## Class: EventEmitter\ # Class: EventEmitter\ EventEmitter is a class designed for managing and dispatching events. ## Extended by - [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) - [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer) - [`TextSelectionPlugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionPlugin) - [`AnnotationManager`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) - [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) - [`Controller`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) - [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution) - [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) ## Type Parameters ### T `T` *extends* `Record`\ `void`\> Interface which describes the event names and their associated callback types. ## Constructors ### Constructor > **new EventEmitter**\<`T`\>(): `EventEmitter`\<`T`\> #### Returns `EventEmitter`\<`T`\> ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<`T`\[`K`\]\> The data associated with the event. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `string` \| `number` \| `symbol` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Returns `void` --- ## Enumeration: LogLevel Enum representing different log levels. ## Enumeration Members ### ALL > **ALL**: `7` *** ### ERROR > **ERROR**: `1` *** ### INFO > **INFO**: `4` *** ### NONE > **NONE**: `0` *** ### WARN > **WARN**: `2` --- ## Function: delay() > **delay**(`seconds`): `Promise`\<`unknown`\> Delays execution for a specified number of seconds. ## Parameters ### seconds `number` The number of seconds to delay. ## Returns `Promise`\<`unknown`\> --- ## Core ## Enumerations - [LogLevel](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/enumerations/LogLevel) ## Classes - [EventEmitter](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter) ## Interfaces - [Cloneable](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable) - [Disposable](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Type Aliases - [Brand](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/type-aliases/Brand) ## Variables - [logger](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/variables/logger) ## Functions - [delay](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/functions/delay) --- ## Interface: Cloneable\(Interfaces) # Interface: Cloneable\ Represents an object that can be cloned to create a deep copy. ## Type Parameters ### T `T` The type of the object that the clone method returns. ## Methods ### clone() > **clone**(): `T` Creates a deep copy of the object. #### Returns `T` A new instance that is a deep copy of the original object. --- ## Interface: Disposable(Interfaces) Disposable defines a contract for objects that require explicit cleanup or resource release when they are no longer needed. Classes implementing this interface should provide a `dispose` method to perform the necessary cleanup. ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Returns `void` --- ## Type Alias: Brand\ # Type Alias: Brand\ > **Brand**\<`T`, `U`\> = `T` & `object` Makes a branded type synonym for distinguishing between types with the same underlying structure at compile time. For example, to distinguish between Km and miles, at compile time, although the underlying type is the same ## Type Declaration ### \[brand\] > **\[brand\]**: `U` ## Type Parameters ### T `T` ### U `U` --- ## Variable: logger > `const` **logger**: `Logger` Singleton instance of the Logger class. --- ## Class: AnnotationManager Class for managing annotations within a PDF document. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<`AnnotationManagerEventMap`\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Constructors ### Constructor > **new AnnotationManager**(`document`): `AnnotationManager` #### Parameters ##### document [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) #### Returns `AnnotationManager` *Overrides [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#constructor)* ## Methods ### add() #### Call Signature > **add**(`annotation`): `Promise`\<`void`\> Adds a single annotation to the document. ##### Parameters ###### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to be added. ##### Returns `Promise`\<`void`\> #### Call Signature > **add**(`annotations`): `Promise`\<`void`\> Adds multiple annotations to the document. ##### Parameters ###### annotations [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[] An array of annotations to be added. ##### Returns `Promise`\<`void`\> *** ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* keyof `AnnotationManagerEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### bringToBack() > **bringToBack**(`annotation`): `void` **`Experimental`** Brings the specified annotation to the back, making it appear below other annotations. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to bring to the back. *** ### bringToFront() > **bringToFront**(`annotation`): `void` **`Experimental`** Brings the specified annotation to the front, making it appear above other annotations. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to bring to the front. *** ### copy() > **copy**(`annotation`): `void` **`Experimental`** Creates a copy of the specified annotation. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to be copied. *** ### delete() #### Call Signature > **delete**(`annotation`): `Promise`\<`void`\> Deletes a single annotation from the document. ##### Parameters ###### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to be deleted. ##### Returns `Promise`\<`void`\> #### Call Signature > **delete**(`annotations`): `Promise`\<`void`\> Deletes multiple annotations from the document. ##### Parameters ###### annotations [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[] An array of annotations to be deleted. ##### Returns `Promise`\<`void`\> #### Call Signature > **delete**(`annotationId`): `Promise`\<`void`\> **`Experimental`** Deletes an annotation by its ID from the document. ##### Parameters ###### annotationId `string` The ID of the annotation to be deleted. ##### Returns `Promise`\<`void`\> *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* keyof `AnnotationManagerEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<`AnnotationManagerEventMap`\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### getAll() > **getAll**(): `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> Retrieves a list of all annotations in the document. #### Returns `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> An array containing all the annotations. *** ### getAllOnPage() > **getAllOnPage**(`pageNumber`): `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> Retrieves annotations on a specific page. #### Parameters ##### pageNumber `number` The page number to retrieve annotations from. #### Returns `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> An array containing all the annotations on a specific page. *** ### getAnnotationsOnPoint() > **getAnnotationsOnPoint**(`pageNumber`, `point`, `onlySelectable`): `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> Gets all annotations on a point on the page. #### Parameters ##### pageNumber `number` The page number to retrieve annotations from. ##### point `PdfPoint` The PDF point on the current page. ##### onlySelectable `boolean` Only return annotations which can be selected. #### Returns `Promise`\<[`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[]\> An array containing all the annotations on point. *** ### getById() > **getById**(`annotationId`): [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) **`Experimental`** Retrieves an annotation by its ID from the document. #### Parameters ##### annotationId `string` The ID of the annotation to retrieve. #### Returns [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The retrieved annotation. *** ### getTextStampAspectRatio() > **getTextStampAspectRatio**(`text`): `Promise`\<`number`\> Calculates the aspect ratio of a custom text stamp based on the provided text. This method retrieves the width-to-height ratio of a text stamp, which can be used to correctly scale the stamp when adding it to a document. #### Parameters ##### text `string` The text content of the custom text stamp for which the aspect ratio is to be calculated. #### Returns `Promise`\<`number`\> A promise that resolves to the aspect ratio (width divided by height) of the custom text stamp. *** ### hide() #### Call Signature > **hide**(`annotation`): `Promise`\<`void`\> Hides the specified annotation, making it invisible within the document. ##### Parameters ###### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to be hidden. ##### Returns `Promise`\<`void`\> #### Call Signature > **hide**(`annotations`): `Promise`\<`void`\> **`Experimental`** Hides multiple annotations, making them invisible within the document. ##### Parameters ###### annotations [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[] An array of annotations to be hidden. ##### Returns `Promise`\<`void`\> *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* keyof `AnnotationManagerEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* keyof `AnnotationManagerEventMap` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener)* *** ### update() #### Call Signature > **update**(`annotation`): `Promise`\<`void`\> Updates a single annotation in the document. ##### Parameters ###### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) The annotation to be updated. ##### Returns `Promise`\<`void`\> #### Call Signature > **update**(`annotations`): `Promise`\<`void`\> Updates multiple annotations in the document. ##### Parameters ###### annotations [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation)[] An array of annotations to be updated. ##### Returns `Promise`\<`void`\> --- ## Class: Controller Class used for managing PDF documents. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`ControllerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/ControllerEventMap)\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Constructors ### Constructor > **new Controller**(`controllerOptions?`): `Controller` #### Parameters ##### controllerOptions? `ControllerOptions` = `{}` #### Returns `Controller` *Overrides [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#constructor)* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"workerErrorOcurred"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"workerErrorOcurred"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`ControllerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/ControllerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### initialize() > **initialize**(): `Promise`\<`Controller`\> #### Returns `Promise`\<`Controller`\> *** ### isFeatureEnabled() > **isFeatureEnabled**(`featureId`): `boolean` #### Parameters ##### featureId [`LicensedFeatureId`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/LicensedFeatureId) #### Returns `boolean` *** ### openDocument() > **openDocument**(`inputDocument`): `Promise`\<[`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document)\> Opens a PDF document from either a file or a remote URI. #### Parameters ##### inputDocument [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputFile) \| [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputUri) The input document to open. #### Returns `Promise`\<[`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document)\> A Promise that resolves to a `Pdf.Document`. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"workerErrorOcurred"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"workerErrorOcurred"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener) --- ## Class: Document Represents a Pdf document. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentEventMap)\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Accessors ### annotations #### Get Signature > **get** **annotations**(): [`AnnotationManager`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) ##### Returns [`AnnotationManager`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) *** ### controller #### Get Signature > **get** **controller**(): [`Controller`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) Gets the `Pdf.Controller` ##### Returns [`Controller`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) *** ### forms #### Get Signature > **get** **forms**(): \[\] ##### Returns \[\] *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` indicates if the document has been changed since the document was opened or last saved ##### Returns `boolean` *** ### initialDestination #### Get Signature > **get** **initialDestination**(): [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) Gets the initial destination from the PDF document. This destination specifies where the viewer should navigate when the document opens. ##### Returns [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) The initial destination, or `undefined` if not specified in the PDF. *** ### pageCount #### Get Signature > **get** **pageCount**(): `number` ##### Returns `number` *** ### pages #### Get Signature > **get** **pages**(): [`PageList`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageList) ##### Returns [`PageList`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageList) ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `never` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `never` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`DocumentEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### getMetadata() > **getMetadata**(): `Promise`\<[`Metadata`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Metadata)\> #### Returns `Promise`\<[`Metadata`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Metadata)\> *** ### loadOutlines() > **loadOutlines**(): `Promise`\<`OutlineItem`[]\> Loads outlines of a `Pdf.Document`. #### Returns `Promise`\<`OutlineItem`[]\> A Promise that resolves to an Array containing the outlines. *** ### loadTextFragments() > **loadTextFragments**(): `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> Loads text fragments of a `Pdf.Document`. #### Returns `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> A Promise that resolves to an Array containing the text fragments. *** ### registerImage() > **registerImage**(`image`): `Promise`\<[`PdfImage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PdfImage)\> Register the image in the PDF document so it can be reused. #### Parameters ##### image `Uint8Array` I #### Returns `Promise`\<[`PdfImage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PdfImage)\> *** ### registerPdfContent() > **registerPdfContent**(`page`): `Promise`\<[`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent)\> Register the PDF page in the PDF document so it can be reused. #### Parameters ##### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The PDF page to register. #### Returns `Promise`\<[`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent)\> A Promise that resolves to the registered PdfContent. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `never` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `never` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener)* *** ### renderPage() > **renderPage**(`pageNumber`, `width`, `height`, `renderOptions?`): `Promise`\<[`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Image)\> Renders a page of the PDF document to an image. #### Parameters ##### pageNumber `number` The page number to render (1-indexed). ##### width `number` The width of the rendered image. ##### height `number` The height of the rendered image. ##### renderOptions? [`PageRenderOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageRenderOptions) Optional rendering options. #### Returns `Promise`\<[`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Image)\> A `Promise` that resolves to the rendered `Image`. *** ### save() > **save**(`options?`): `Promise`\<`Blob`\> Saves the changes made to the `Pdf.Document`. #### Parameters ##### options? [`DocumentSaveOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentSaveOptions) = `defaultDocumentSaveOptions` Options for configuring the document save behavior. #### Returns `Promise`\<`Blob`\> A Promise that resolves to a Blob containing the updated PDF document. --- ## Class: FileNotFoundError ## Extends - `Error` ## Constructors ### Constructor > **new FileNotFoundError**(`message?`): `FileNotFoundError` #### Parameters ##### message? `string` #### Returns `FileNotFoundError` *Inherited from `Error.constructor`* ### Constructor > **new FileNotFoundError**(`message?`, `options?`): `FileNotFoundError` #### Parameters ##### message? `string` ##### options? `ErrorOptions` #### Returns `FileNotFoundError` *Inherited from `Error.constructor`* ## Properties ### cause? > `optional` **cause?**: `unknown` *Inherited from `Error.cause`* *** ### message > **message**: `string` *Inherited from `Error.message`* *** ### name > **name**: `string` = `'FileNotFoundError'` *Overrides `Error.name`* *** ### stack? > `optional` **stack?**: `string` #### Inherited from `Error.stack` --- ## Class: InvalidPasswordError ## Extends - `Error` ## Constructors ### Constructor > **new InvalidPasswordError**(`message?`): `InvalidPasswordError` #### Parameters ##### message? `string` #### Returns `InvalidPasswordError` *Inherited from `Error.constructor`* ### Constructor > **new InvalidPasswordError**(`message?`, `options?`): `InvalidPasswordError` #### Parameters ##### message? `string` ##### options? `ErrorOptions` #### Returns `InvalidPasswordError` *Inherited from `Error.constructor`* ## Properties ### cause? > `optional` **cause?**: `unknown` *Inherited from `Error.cause`* *** ### message > **message**: `string` *Inherited from `Error.message`* *** ### name > **name**: `string` = `'InvalidPasswordError'` *Overrides `Error.name`* *** ### stack? > `optional` **stack?**: `string` #### Inherited from `Error.stack` --- ## Class: Metadata Document metadata according to the PDF standard (PDF 1.7) ## Constructors ### Constructor > **new Metadata**(): `Metadata` #### Returns `Metadata` ## Properties ### author > **author**: `string` The name of the person who created the document. *** ### creationDate > **creationDate**: `Date` The date and time the document was created. *** ### creator > **creator**: `string` If the document was converted to PDF from another format, the name of the application that created the original document from which it was converted. *** ### keywords > **keywords**: `string` Keywords associated with the document. *** ### modificationDate > **modificationDate**: `Date` The date and time the document was most recently modified. *** ### producer > **producer**: `string` If the document was converted to PDF from another format, the name of the application that converted it to PDF. *** ### subject > **subject**: `string` The subject of the document. *** ### title > **title**: `string` The document's title. --- ## Class: NotLoadedError ## Extends - `Error` ## Constructors ### Constructor > **new NotLoadedError**(`message?`): `NotLoadedError` #### Parameters ##### message? `string` #### Returns `NotLoadedError` *Inherited from `Error.constructor`* ### Constructor > **new NotLoadedError**(`message?`, `options?`): `NotLoadedError` #### Parameters ##### message? `string` ##### options? `ErrorOptions` #### Returns `NotLoadedError` *Inherited from `Error.constructor`* ## Properties ### cause? > `optional` **cause?**: `unknown` *Inherited from `Error.cause`* *** ### message > **message**: `string` *Inherited from `Error.message`* *** ### name > **name**: `string` = `'NotLoadedError'` *Overrides `Error.name`* *** ### stack? > `optional` **stack?**: `string` #### Inherited from `Error.stack` --- ## Class: Page A single page in a Pdf document. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`PageEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PageEventMap)\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Accessors ### document #### Get Signature > **get** **document**(): [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) the pdf document to which the page belongs ##### Returns [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` indicates if the page or its content has been changed since the document was last saved ##### Returns `boolean` *** ### height #### Get Signature > **get** **height**(): `number` Height of the page in PDF coordinates. This represents the height of the page, taking into account the rotation. ##### Returns `number` *** ### isDeleted #### Get Signature > **get** **isDeleted**(): `boolean` indicates whether the page was deleted ##### Returns `boolean` *** ### originalHeight #### Get Signature > **get** **originalHeight**(): `number` Original height of the page in PDF coordinates. This represents the original height of the page without considering any rotation. ##### Returns `number` *** ### originalWidth #### Get Signature > **get** **originalWidth**(): `number` Original width of the page in PDF coordinates. This represents the original width of the page without considering any rotation. ##### Returns `number` *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` page number ##### Returns `number` *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) Rotation of the page ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) *** ### width #### Get Signature > **get** **width**(): `number` Width of the page in PDF coordinates. This represents the width of the page, taking into account the rotation. ##### Returns `number` ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`PageEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PageEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### getTextFragments() > **getTextFragments**(): [`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[] Gets text fragments of a `Pdf.Page`. #### Returns [`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[] A Promise that resolves to an Array containing the text fragments. #### Throws `Pdf.NotLoadedError` if text fragments are not loaded yet. *** ### loadTextFragments() > **loadTextFragments**(): `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> Loads text fragments of a `Pdf.Page`. #### Returns `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> A Promise that resolves to an Array containing the text fragments. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"textFragmentsLoaded"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener)* *** ### render() > **render**(`renderOptions`): `Promise`\<`Blob`\> Render the given page #### Parameters ##### renderOptions [`PageRenderOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageRenderOptions) Options for rendering the page #### Returns `Promise`\<`Blob`\> Blob containing the image data *** ### rotate() > **rotate**(`direction`, `degree?`): `void` Rotates the page in the specified direction by the specified degree The rotation can only be done in steps of 90 degrees or a multiple thereof #### Parameters ##### direction [`RotationDirection`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/RotationDirection) clockwise or counter-clockwise ##### degree? `number` = `90` rotation in degrees in multiples of 90 *** ### transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral() > **transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\> Converts a quadrilateral from document view coordinates to PDF coordinates. This function transforms a `Quadrilateral`, which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen, to a `Quadrilateral`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`DocumentViewPoint`\> The `Quadrilateral` object representing the quadrilateral in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\> A new instance of `Quadrilateral` representing the converted coordinates in PDF units. *** ### transformDocumentViewPointRectangleToPdfPointRectangle() > **transformDocumentViewPointRectangleToPdfPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Converts a rectangle from document view coordinates to PDF coordinates. This function transforms a `Rectangle`, which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen, to a `Rectangle`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`DocumentViewPoint`\> The `Rectangle` object representing the rectangle in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> A new instance of `Rectangle` representing the converted coordinates in PDF units. *** ### transformDocumentViewPointToPdfPoint() > **transformDocumentViewPointToPdfPoint**(`point`, `width`, `height`, `rotation`): `PdfPoint` Converts a point from document view coordinates to PDF coordinates. This function transforms a `DocumentViewPoint`, which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen, to a `PdfPoint`, which is measured in PDF units. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### point `DocumentViewPoint` The `DocumentViewPoint` object representing the point in document view coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns `PdfPoint` A new instance of `PdfPoint` representing the converted coordinates in PDF units. *** ### transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral() > **transformPdfPointQuadrilateralToDocumentViewPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`DocumentViewPoint`\> Converts a quadrilateral from PDF coordinates to document view coordinates. This function transforms a `Quadrilateral`, which is measured in PDF units, to a `Quadrilateral`, which corresponds to a quadrilateral scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\> The `Quadrilateral` object representing the quadrilateral in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`DocumentViewPoint`\> A new instance of `Quadrilateral` representing the converted coordinates in document view units. *** ### transformPdfPointRectangleToDocumentViewPointRectangle() > **transformPdfPointRectangleToDocumentViewPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`DocumentViewPoint`\> Converts a rectangle from PDF coordinates to document view coordinates. This function transforms a `Rectangle`, which is measured in PDF units, to a `Rectangle`, which corresponds to a rectangle scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> The `Rectangle` object representing the rectangle in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`DocumentViewPoint`\> A new instance of `Rectangle` representing the converted coordinates in document view units. *** ### transformPdfPointToDocumentViewPoint() > **transformPdfPointToDocumentViewPoint**(`point`, `width`, `height`, `rotation`): `DocumentViewPoint` Converts a point from PDF coordinates to document view coordinates. This function transforms a `PdfPoint`, which is measured in PDF units, to a `DocumentViewPoint`, which corresponds to a PDF point scaled proportionally based on the rendered size of the page on screen. The conversion takes into account the dimensions of the document view page canvas and the rotation of the page. #### Parameters ##### point `PdfPoint` The `PdfPoint` object representing the point in PDF coordinates. ##### width `number` The width of the document view page canvas. ##### height `number` The height of the document view page canvas. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation of the page. #### Returns `DocumentViewPoint` A new instance of `DocumentViewPoint` representing the converted coordinates in document view units. *** ### calculateRotatedDocumentViewPoint() > `static` **calculateRotatedDocumentViewPoint**(`point`, `rotation`, `pageWidth`, `pageHeight`): `DocumentViewPoint` Calculates rotated document view point around page center. #### Parameters ##### point `DocumentViewPoint` The `DocumentViewPoint` object representing point to be rotated around page center. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation value to apply to a point. ##### pageWidth `number` ##### pageHeight `number` #### Returns `DocumentViewPoint` A new instance of `DocumentViewPoint` representing the rotated point around page center. *** ### calculateRotatedPdfPoint() > `static` **calculateRotatedPdfPoint**(`point`, `rotation`, `pageWidth`, `pageHeight`): `PdfPoint` Calculates rotated PDF point around center page center. #### Parameters ##### point `PdfPoint` The `PdfPoint` object representing point to be rotated around page center. ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) The rotation value to apply to a point. ##### pageWidth `number` ##### pageHeight `number` #### Returns `PdfPoint` A new instance of `PdfPoint` representing the rotated point around page center. --- ## Class: PageList Class for all page-related operations in a PDF document. ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Methods ### add() #### Call Signature > **add**(`page`, `index?`): `Promise`\<`void`\> **`Experimental`** Adds a page to the document. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page to be added. ###### index? `number` Page index on which page will be added to the document. If not provided, the default is to add the page at the end of the document. ##### Returns `Promise`\<`void`\> #### Call Signature > **add**(`pages`, `index?`): `Promise`\<`void`\> **`Experimental`** Adds multiple pages to the document. ##### Parameters ###### pages [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page)[] Pages to be added. ###### index? `number` Page index on which first page in the array will be added. Other pages will be added consecutively after the first one. If not provided, the default is to add the pages at the end of the document. ##### Returns `Promise`\<`void`\> *** ### delete() #### Call Signature > **delete**(`page`): `Promise`\<`void`\> **`Experimental`** Deletes a single page from the document. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to be deleted. ##### Returns `Promise`\<`void`\> #### Call Signature > **delete**(`pages`): `Promise`\<`void`\> **`Experimental`** Deletes multiple pages from the document. ##### Parameters ###### pages [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page)[] An array of pages to be deleted. ##### Returns `Promise`\<`void`\> *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### getAll() > **getAll**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page)[] Get an array with all pages in the document. #### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page)[] An array of Page objects representing all pages in the document. *** ### getByIndex() > **getByIndex**(`pageIndex`): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Get a page by index. #### Parameters ##### pageIndex `number` The index of the page to retrieve. #### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The Page object at the specified index. *** ### getByNumber() > **getByNumber**(`pageNumber`): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Get a page by its page number. #### Parameters ##### pageNumber `number` The page number to search for. #### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The Page object with the specified page number, or undefined if not found. *** ### rotate() #### Call Signature > **rotate**(`page`, `options?`): `Promise`\<`void`\> **`Experimental`** Rotates a single page. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page to be rotated. ###### options? Optional parameters for specifying the rotation angle. ###### absoluteRotation `number` ###### rotation `number` ##### Returns `Promise`\<`void`\> #### Call Signature > **rotate**(`pages`, `options?`): `Promise`\<`void`\> **`Experimental`** Rotates multiple pages. ##### Parameters ###### pages [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page)[] An array of pages to be rotated. ###### options? Optional parameters for specifying the rotation angle. ###### absoluteRotation `number` ###### rotation `number` ##### Returns `Promise`\<`void`\> --- ## Class: PageRenderOptions(Classes) **`Experimental`** ## Constructors ### Constructor > **new PageRenderOptions**(): `PageRenderOptions` **`Experimental`** #### Returns `PageRenderOptions` ## Properties ### noPrint > **noPrint**: `boolean` **`Experimental`** *** ### outputMedium? > `optional` **outputMedium?**: [`OutputMedium`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/OutputMedium) **`Experimental`** The intended target for page rendering. When set to `OutputMedium.Print`, annotations with `printable=false` will not be rendered. ## Accessors ### annotationFilter #### Set Signature > **set** **annotationFilter**(`filter`): `void` **`Experimental`** ##### Parameters ###### filter () => `object` ##### Returns `void` --- ## Enumeration: DestinationType(Enumerations) Supported PDF destination types ## Enumeration Members ### Direct > **Direct**: `1` A destination that directly points to a specific location in the document. *** ### FitHeight > **FitHeight**: `6` A destination fits the height of a page into the viewport. *** ### FitPage > **FitPage**: `4` A destination fits an entire page into the viewport. *** ### FitRectangle > **FitRectangle**: `0` A destination that fits a specified area of a page into the viewport. *** ### FitWidth > **FitWidth**: `5` A destination fits the width of a page into the viewport. *** ### LocationZoom > **LocationZoom**: `2` A destination that points to a specific location on the target page, using a specified zoom factor. The location is displayed in the top left corner of the viewport (if possible). *** ### Named > **Named**: `3` A destination that can be referred by name. --- ## Enumeration: FitMode(Enumerations) Setting how the viewport will be fitted to the visible content ## Enumeration Members ### FitPage > **FitPage**: `2` Fit viewport to be able to show largest visible page in its entirety *** ### FitWidth > **FitWidth**: `1` Fit viewport to width of widest visible page *** ### None > **None**: `0` Do not fit --- ## Enumeration: LicensedFeatureId Enum representing a unique identifier for each PDF Web SDK licensed feature. Each feature is represented by a bit flag, allowing multiple features to be combined using bitwise operations. ## Enumeration Members ### AnnotationAdding > **AnnotationAdding**: `2` Adding annotations to a document. Grants users the ability to create new annotations. *** ### AnnotationDeleting > **AnnotationDeleting**: `8` Deleting annotations from a document. Enables users to remove existing annotations permanently. *** ### AnnotationHistory > **AnnotationHistory**: `16` Viewing and interacting with an annotation's history. Provides access to the historical changes and revisions made to annotations. *** ### AnnotationReading > **AnnotationReading**: `1` Reading and inspecting annotations in a document. Enables users to fetch existing annotations without making modifications. *** ### AnnotationUpdating > **AnnotationUpdating**: `4` Updating existing annotations in a document. Allows users to modify properties or contents of previously created annotations. *** ### AutomatedTextProcessing > **AutomatedTextProcessing**: `64` Automated text processing capabilities. Enables the retrieval of text content within the document, including its position, bounding box, and glyph offsets. *** ### DocumentMerging > **DocumentMerging**: `1024` Merging multiple PDF documents into a single file. Provides functionality to combine pages and content from separate documents. *** ### FormFieldFilling > **FormFieldFilling**: `32` Filling form fields in a document. Enables users to fill out or edit form fields such as text boxes, checkboxes, and dropdowns. *** ### PageAdding > **PageAdding**: `128` Adding blank pages to the document. Grants users the ability to insert new, empty pages at specific positions within the document. *** ### PageDeleting > **PageDeleting**: `256` Deleting pages from the document. Allows users to remove existing pages from a document. *** ### PageRotation > **PageRotation**: `512` Rotating pages within the document. Enables users to change the orientation of pages (e.g., 90°, 180° rotation). *** ### Redaction > **Redaction**: `2048` Redacting sensitive information from the document. Allows users to permanently remove confidential content. --- ## Enumeration: OutputMedium The intended target for page rendering. ## Enumeration Members ### Display > **Display**: `0` Show rendered output on a display. *** ### Print > **Print**: `1` Print rendered output onto paper. When set to `Print`, annotations with `printable=false` will not be rendered. --- ## Enumeration: PageLayoutMode(Enumerations) Setting how the pages will be arranged on the viewport. According to the PDF standard (PDF 1.7) ## Enumeration Members ### OneColumn > **OneColumn**: `1` Display the pages in one column. *** ### SinglePage > **SinglePage**: `0` Display one page at a time . *** ### TwoColumnLeft > **TwoColumnLeft**: `2` Display the pages in two columns, with odd-numbered pages on the left. *** ### TwoColumnRight > **TwoColumnRight**: `3` Display the pages in two columns, with odd-numbered pages on the right. *** ### TwoPageLeft > **TwoPageLeft**: `4` Display two pages at a time, with odd-numbered pages on the left. *** ### TwoPageRight > **TwoPageRight**: `5` Display two pages at a time, with odd-numbered pages on the right. --- ## Enumeration: Rotation(Enumerations) Enumerates different rotation values in 90 degree steps. ## Enumeration Members ### Clockwise > **Clockwise**: `90` Represents 90 degree clockwise rotation. *** ### CounterClockwise > **CounterClockwise**: `270` Represents 270 degree counter-clockwise rotation. *** ### None > **None**: `0` Represents 0 degree rotation (no rotation). *** ### UpsideDown > **UpsideDown**: `180` Represents 180 degree rotation (upside down). --- ## Enumeration: RotationDirection ## Enumeration Members ### clockwise > **clockwise**: `0` *** ### counterClockwise > **counterClockwise**: `1` --- ## Pdf ## Namespaces - [Actions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/) - [Annotations](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/) - [Drawing](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/) - [Forms](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/) - [Geometry](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/) - [Search](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/) ## Enumerations - [DestinationType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/DestinationType) - [FitMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) - [LicensedFeatureId](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/LicensedFeatureId) - [OutputMedium](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/OutputMedium) - [PageLayoutMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) - [Rotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) - [RotationDirection](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/RotationDirection) ## Classes - [AnnotationManager](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/AnnotationManager) - [Controller](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Controller) - [Document](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) - [FileNotFoundError](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/FileNotFoundError) - [InvalidPasswordError](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/InvalidPasswordError) - [Metadata](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Metadata) - [NotLoadedError](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/NotLoadedError) - [Page](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) - [PageList](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageList) - [PageRenderOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/PageRenderOptions) ## Interfaces - [ControllerEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/ControllerEventMap) - [Destination](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) - [DocumentEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentEventMap) - [DocumentSaveOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/DocumentSaveOptions) - [HttpOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/HttpOptions) - [InputDocument](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument) - [InputFile](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputFile) - [InputUri](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputUri) - [PageEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PageEventMap) - [PdfImage](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PdfImage) - [SaveOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/SaveOptions) - [TextFragment](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment) --- ## Interface: ControllerEventMap Interface defining event types for `Pdf.Controller`. ## Properties ### workerErrorOcurred > **workerErrorOcurred**: (`error`) => `void` Event triggered when a worker task fails The event payload is an `Error` #### Parameters ##### error `Error` #### Returns `void` --- ## Interface: Destination(Interfaces) ## Properties ### bottom? > `optional` **bottom?**: `number` *** ### centering? > `optional` **centering?**: `boolean` *** ### destinationType > **destinationType**: [`DestinationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/DestinationType) *** ### fitContent? > `optional` **fitContent?**: `boolean` *** ### left? > `optional` **left?**: `number` *** ### pageNumber > **pageNumber**: `number` *** ### rectangle? > `optional` **rectangle?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> *** ### right? > `optional` **right?**: `number` *** ### top? > `optional` **top?**: `number` *** ### zoom? > `optional` **zoom?**: `number` --- ## Interface: DocumentEventMap Interface defining event types for `Pdf.Document`. --- ## Interface: DocumentSaveOptions(Interfaces) Options for configuring the document save behavior. ## Properties ### saveAsFdf? > `optional` **saveAsFdf?**: `boolean` Indicates whether to save the document in FDF format, which includes only the form data and annotations. #### Default Value `false` *** ### saveOriginal? > `optional` **saveOriginal?**: `boolean` Indicates whether to save the original input document, discarding any interactive changes. When set to true, it bypasses the regular save process, avoiding any automatic repairs or modifications. #### Default Value `false` *** ### shouldApplyRedactions? > `optional` **shouldApplyRedactions?**: `boolean` Indicates whether to apply redactions to the document when saving. #### Default Value `false` --- ## Interface: HttpOptions Options that are applied to an HTTP request. ## Properties ### headers? > `optional` **headers?**: `object` A set of custom HTTP headers to include in the request. Each header is represented as a key-value pair, where the key is the header name and the value is the header value. These headers will be sent with the HTTP request when loading a document from a URI. #### Index Signature \[`key`: `string`\]: `string` --- ## Interface: InputDocument ## Extended by - [`InputFile`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputFile) - [`InputUri`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputUri) ## Properties ### annotationTag? > `optional` **annotationTag?**: `string` Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF). *** ### autoRepairDisabled? > `optional` **autoRepairDisabled?**: `boolean` A boolean property that controls whether automatic repairs on PDF files are disabled. Setting this property to `true` prevents the application from performing any automatic repair operations on PDF files, which could alter the file's structure and potentially invalidate digital signatures within the document. #### Default Value `false` *** ### fileName? > `optional` **fileName?**: `string` Name for the input document *** ### password? > `optional` **password?**: `string` The password used for opening the PdfDocument. --- ## Interface: InputFile(Interfaces) A file that can be opened on a `Blob`, `File` or `Uint8Array`. ## Extends - [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument) ## Properties ### annotationTag? > `optional` **annotationTag?**: `string` Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF). *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`annotationTag`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#annotationtag)* *** ### autoRepairDisabled? > `optional` **autoRepairDisabled?**: `boolean` A boolean property that controls whether automatic repairs on PDF files are disabled. Setting this property to `true` prevents the application from performing any automatic repair operations on PDF files, which could alter the file's structure and potentially invalidate digital signatures within the document. #### Default Value `false` *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`autoRepairDisabled`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#autorepairdisabled)* *** ### data > **data**: `Uint8Array`\<`ArrayBufferLike`\> \| `Blob` \| `File` A `Blob`, `File` or `Uint8Array` containing the file. *** ### fileName? > `optional` **fileName?**: `string` Name for the input document *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`fileName`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#filename)* *** ### password? > `optional` **password?**: `string` The password used for opening the PdfDocument. #### Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`password`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#password) --- ## Interface: InputUri(Interfaces) A file that can be opened on a text-uri. ## Extends - [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument) ## Properties ### annotationTag? > `optional` **annotationTag?**: `string` Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF). *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`annotationTag`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#annotationtag)* *** ### autoRepairDisabled? > `optional` **autoRepairDisabled?**: `boolean` A boolean property that controls whether automatic repairs on PDF files are disabled. Setting this property to `true` prevents the application from performing any automatic repair operations on PDF files, which could alter the file's structure and potentially invalidate digital signatures within the document. #### Default Value `false` *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`autoRepairDisabled`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#autorepairdisabled)* *** ### fileName? > `optional` **fileName?**: `string` Name for the input document *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`fileName`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#filename)* *** ### httpOptions? > `optional` **httpOptions?**: [`HttpOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/HttpOptions) Options that are applied to a HTTP request. *** ### password? > `optional` **password?**: `string` The password used for opening the PdfDocument. *Inherited from [`InputDocument`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument).[`password`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/InputDocument#password)* *** ### uri > **uri**: `string` The uri where the file can be loaded from. --- ## Interface: PageEventMap Interface defining event types for `Pdf.Page`. ## Properties ### textFragmentsLoaded > **textFragmentsLoaded**: (`textFragments`) => `void` Event triggered when text fragments of a page are loaded. The event payload is an array of text fragments. #### Parameters ##### textFragments [`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[] #### Returns `void` --- ## Interface: PdfImage An interface representing an image which is registered in a PDF document and can be reused. ## Properties ### id > **id**: `number` --- ## Interface: SaveOptions Options used for saving [Pdf.Document](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document)s. ## Properties ### annotationFilter? > `optional` **annotationFilter?**: (`annotation`) => `boolean` A callback to be called for each annotation in the document when saving. The result of the callback determines whether the annotation is included in the output. Pass `null` to save all annotations. #### Parameters ##### annotation [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) #### Returns `boolean` #### Default Value `undefined` *** ### fileType > **fileType**: `"Pdf"` \| `"Fdf"` Choose whether the output file should be a PDF or an FDF document. #### Default Value `'Pdf'` *** ### optionalContentFilter? > `optional` **optionalContentFilter?**: () => `boolean` #### Returns `boolean` #### Default Value `undefined` --- ## Interface: TextFragment(Interfaces) Represents a text fragment within a document, containing information about its position, content, and layout. ## Properties ### glyphOffsets > **glyphOffsets**: `number`[] An array of glyph offsets representing the offset of each character within the text fragment. Glyph offsets are used for precise positioning and layout purposes. *** ### pageNumber > **pageNumber**: `number` The page number where the text fragment is located within the document. *** ### quadrilateral > **quadrilateral**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\> A quadrilateral representing the bounding box or area occupied by the text fragment. This quadrilateral defines the spatial extent of the text fragment on the page. *** ### text > **text**: `string` The actual textual content of the text fragment. --- ## Abstract Class: Action **`Experimental`** Base class for actions. Each subclass represents an interaction the user can perform with the viewer. For example: Go to a specific point in the document. ## Extended by - [`GoToAction`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/GoToAction) - [`RemoteGoToAction`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/RemoteGoToAction) - [`ResetFormAction`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/ResetFormAction) - [`SubmitFormAction`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/SubmitFormAction) - [`UriAction`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/UriAction) ## Constructors ### Constructor > **new Action**(): `Action` **`Experimental`** #### Returns `Action` --- ## Class: GoToAction **`Experimental`** GoToAction Go to a specific point in the document. ## Extends - [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) ## Constructors ### Constructor > **new GoToAction**(): `GoToAction` **`Experimental`** #### Returns `GoToAction` #### Inherited from [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action#constructor) --- ## Class: RemoteGoToAction **`Experimental`** RemoteGoToAction Go to some remote location outside the current document. ## Extends - [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) ## Constructors ### Constructor > **new RemoteGoToAction**(): `RemoteGoToAction` **`Experimental`** #### Returns `RemoteGoToAction` #### Inherited from [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action#constructor) --- ## Class: ResetFormAction **`Experimental`** ResetFormAction Reset the current form. ## Extends - [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) ## Constructors ### Constructor > **new ResetFormAction**(): `ResetFormAction` **`Experimental`** #### Returns `ResetFormAction` #### Inherited from [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action#constructor) --- ## Class: SubmitFormAction **`Experimental`** SubmitFormAction Submit the current form. ## Extends - [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) ## Constructors ### Constructor > **new SubmitFormAction**(): `SubmitFormAction` **`Experimental`** #### Returns `SubmitFormAction` #### Inherited from [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action#constructor) --- ## Class: UriAction **`Experimental`** UriAction Go to a specified URI. ## Extends - [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) ## Constructors ### Constructor > **new UriAction**(`uri`): `UriAction` **`Experimental`** #### Parameters ##### uri `string` #### Returns `UriAction` *Overrides [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action#constructor)* ## Properties ### uri > **uri**: `string` **`Experimental`** --- ## Actions ## Classes - [Action](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) - [GoToAction](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/GoToAction) - [RemoteGoToAction](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/RemoteGoToAction) - [ResetFormAction](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/ResetFormAction) - [SubmitFormAction](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/SubmitFormAction) - [UriAction](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/UriAction) --- ## Abstract Class: Annotation Base class for all annotations. ## Extended by - [`LinkAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/LinkAnnotation) - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) - [`WatermarkAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WatermarkAnnotation) - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) - [`InternalLinkAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/InternalLinkAnnotation) ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Constructors ### Constructor > **new Annotation**(`options`): `Annotation` Creates a new `Annotation` instance. #### Parameters ##### options [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) Options used to initialize annotation. #### Returns `Annotation` ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *** ### isMaintainingAspectRatio #### Get Signature > **get** `abstract` **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *** ### isMarkupAnnotation #### Get Signature > **get** `abstract` **isMarkupAnnotation**(): `boolean` Indicates if the annotation is a markup annotation ##### Returns `boolean` *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *** ### isMoveable #### Get Signature > **get** `abstract` **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *** ### isResizable #### Get Signature > **get** `abstract` **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *** ### isRotatable #### Get Signature > **get** `abstract` **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *** ### isSelectable #### Get Signature > **get** `abstract` **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *** ### isWidgetAnnotation #### Get Signature > **get** `abstract` **isWidgetAnnotation**(): `boolean` Indicates if the annotation is a widget annotation ##### Returns `boolean` *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose) --- ## Class: AnnotationRenderProperties(Classes) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. ## Constructors ### Constructor > **new AnnotationRenderProperties**(): `AnnotationRenderProperties` #### Returns `AnnotationRenderProperties` ## Accessors ### fixedRotation #### Get Signature > **get** **fixedRotation**(): `boolean` Specifies whether the annotation's appearance should remain fixed in orientation when the page is rotated. ##### Returns `boolean` #### Set Signature > **set** **fixedRotation**(`fixedRotation`): `void` ##### Parameters ###### fixedRotation `boolean` # *** ### fixedZoom #### Get Signature > **get** **fixedZoom**(): `boolean` Indicates whether the annotation's appearance should remain fixed in scale when the page's magnification level is changed. ##### Returns `boolean` #### Set Signature > **set** **fixedZoom**(`fixedZoom`): `void` ##### Parameters ###### fixedZoom `boolean` # *** ### renderToPrint #### Get Signature > **get** **renderToPrint**(): `boolean` Specifies whether the annotation should be printed when the page is printed, regardless of its visibility on the screen. ##### Returns `boolean` #### Set Signature > **set** **renderToPrint**(`renderToPrint`): `void` ##### Parameters ###### renderToPrint `boolean` # *** ### renderToScreen #### Get Signature > **get** **renderToScreen**(): `boolean` If set to false, the annotation will not be displayed on the screen and interaction with the user will be disabled. The annotation may be printed (depending on the setting of the `renderToPrint` flag), but it should be considered hidden for purposes of onscreen display and user interaction. ##### Returns `boolean` #### Set Signature > **set** **renderToScreen**(`renderToScreen`): `void` ##### Parameters ###### renderToScreen `boolean` ##### Returns `void` --- ## Class: CaretAnnotation **`Experimental`** An annotation that marks a point to insert text ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new CaretAnnotation**(`options`): `CaretAnnotation` **`Experimental`** Creates a new `CaretAnnotation` instance. #### Parameters ##### options [`CaretAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CaretAnnotationOptions) Options used to initialize annotation. #### Returns `CaretAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Caret` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Abstract Class: DrawingAnnotation(Classes) **`Experimental`** Base class for drawing annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Extended by - [`InkAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/InkAnnotation) - [`LineAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/LineAnnotation) - [`PolyLineAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/PolyLineAnnotation) - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation) ## Constructors ### Constructor > **new DrawingAnnotation**(`options`): `DrawingAnnotation` **`Experimental`** Creates a new `DrawingAnnotation` instance. #### Parameters ##### options [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) Options used to initialize annotation. #### Returns `DrawingAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Class: EllipseAnnotation(Classes) **`Experimental`** An ellipse drawing annotation ## Extends - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation) ## Constructors ### Constructor > **new EllipseAnnotation**(`options`): `EllipseAnnotation` **`Experimental`** Creates a new `EllipseAnnotation` instance. #### Parameters ##### options [`EllipseAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/EllipseAnnotationOptions) Options used to initialize annotation. #### Returns `EllipseAnnotation` *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#blendmode)* *** ### borderEffect #### Get Signature > **get** **borderEffect**(): `BorderEffect` **`Experimental`** Gets the border effect of the ellipse annotation. ##### Returns `BorderEffect` #### Set Signature > **set** **borderEffect**(`value`): `void` **`Experimental`** Sets the border effect of the ellipse annotation. ##### Parameters ###### value `BorderEffect` # *** ### borderIntensity #### Get Signature > **get** **borderIntensity**(): `number` **`Experimental`** Gets the border intensity of the ellipse annotation. ##### Returns `number` #### Set Signature > **set** **borderIntensity**(`value`): `void` **`Experimental`** Sets the border intensity of the ellipse annotation. ##### Parameters ###### value `number` # *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Gets the fill color of the ellipse annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) #### Set Signature > **set** **fillColor**(`value`): `void` **`Experimental`** Sets the fill color of the ellipse annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#iswidgetannotation)* *** ### lineColor #### Get Signature > **get** **lineColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Gets the line color of the ellipse annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) #### Set Signature > **set** **lineColor**(`value`): `void` **`Experimental`** Sets the line color of the ellipse annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the ellipse annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the ellipse annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#dispose) --- ## Abstract Class: FileAttachmentAnnotation **`Experimental`** A file attachment annotation ## Remarks A file attachment annotation (PDF 1.3) contains a reference to a file, which typically is embedded in the PDF file. ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new FileAttachmentAnnotation**(`options`): `FileAttachmentAnnotation` **`Experimental`** Creates a new `FileAttachmentAnnotation` instance. #### Parameters ##### options [`FileAttachmentAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FileAttachmentAnnotationOptions) Options used to initialize annotation. #### Returns `FileAttachmentAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Properties ### icon > **icon**: [`FileAttachmentAnnotationIcon`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/FileAttachmentAnnotationIcon) **`Experimental`** The icon to be used in displaying the annotation. ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Class: FreeTextAnnotation(Classes) An annotation that displays text For a free-text annotation, the annotation's content is used as text to be displayed as the annotation's visual manifestation on the page. ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new FreeTextAnnotation**(`options`): `FreeTextAnnotation` Creates a new `FreeTextAnnotation` instance. #### Parameters ##### options [`FreeTextAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FreeTextAnnotationOptions) Options used to initialize annotation. #### Returns `FreeTextAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### backgroundColor #### Get Signature > **get** **backgroundColor**(): `string` Background color for the annotation. ##### Returns `string` #### Set Signature > **set** **backgroundColor**(`color`): `void` ##### Parameters ###### color `string` # *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Parameters ###### content `string` # *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### richText #### Get Signature > **get** **richText**(): `string` A rich text string that shall be displayed in the popup window when the annotation is opened. ##### Returns `string` #### Set Signature > **set** **richText**(`richText`): `void` ##### Parameters ###### richText `string` # *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) Rotation of the annotation ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) #### Set Signature > **set** **rotation**(`rotation`): `void` ##### Parameters ###### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) # *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Class: InkAnnotation **`Experimental`** A free-hand drawing annotation ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) ## Constructors ### Constructor > **new InkAnnotation**(`options`): `InkAnnotation` **`Experimental`** Creates a new `InkAnnotation` instance. #### Parameters ##### options [`InkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InkAnnotationOptions) Options used to initialize annotation. #### Returns `InkAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#iswidgetannotation)* *** ### lineColor #### Get Signature > **get** **lineColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Gets the line color of the ink annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) #### Set Signature > **set** **lineColor**(`value`): `void` **`Experimental`** Sets the line color of the ink annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the ink annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the ink annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#source)* *** ### strokes #### Get Signature > **get** **strokes**(): `PdfPoint`[][] **`Experimental`** Gets the strokes of the ink annotation. Each stroke is an array of points representing a continuous line segment. ##### Returns `PdfPoint`[][] #### Set Signature > **set** **strokes**(`value`): `void` **`Experimental`** Sets the strokes of the ink annotation. Each stroke is an array of points representing a continuous line segment. ##### Parameters ###### value `PdfPoint`[][] # *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#dispose) --- ## Class: InternalLinkAnnotation **`Experimental`** An InternalLink annotation ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) ## Constructors ### Constructor > **new InternalLinkAnnotation**(`options`): `InternalLinkAnnotation` **`Experimental`** Creates a new `NoteAnnotation` instance. #### Parameters ##### options [`InternalLinkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InternalLinkAnnotationOptions) Options used to initialize annotation. #### Returns `InternalLinkAnnotation` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#constructor)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#datemodified)* *** ### destination #### Get Signature > **get** **destination**(): [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) **`Experimental`** Gets the destination of the InternalLink annotation. The destination represents the target location within the PDF document that the internal link will navigate to when activated. ##### Returns [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#dispose) --- ## Class: LineAnnotation(Classes) **`Experimental`** A line annotation ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) ## Constructors ### Constructor > **new LineAnnotation**(`options`): `LineAnnotation` **`Experimental`** Creates a new `LineAnnotation` instance. #### Parameters ##### options [`LineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LineAnnotationOptions) Options used to initialize annotation. #### Returns `LineAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#boundingbox)* *** ### color #### Get Signature > **get** **color**(): [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) **`Experimental`** Gets the color of the line annotation. ##### Returns [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) #### Set Signature > **set** **color**(`value`): `void` **`Experimental`** Sets the color of the line annotation. ##### Parameters ###### value [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) # *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#datemodified)* *** ### endPoint #### Get Signature > **get** **endPoint**(): `PdfPoint` **`Experimental`** Gets the end point of the line annotation. ##### Returns `PdfPoint` #### Set Signature > **set** **endPoint**(`value`): `void` **`Experimental`** Sets the end point of the line annotation. ##### Parameters ###### value `PdfPoint` # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#iswidgetannotation)* *** ### lineEndingAtEnd #### Get Signature > **get** **lineEndingAtEnd**(): [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) **`Experimental`** Gets the line ending at the end of the line annotation. ##### Returns [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) #### Set Signature > **set** **lineEndingAtEnd**(`value`): `void` **`Experimental`** Sets the line ending at the end of the line annotation. ##### Parameters ###### value [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) # *** ### lineEndingAtStart #### Get Signature > **get** **lineEndingAtStart**(): [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) **`Experimental`** Gets the line ending at the start of the line annotation. ##### Returns [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) #### Set Signature > **set** **lineEndingAtStart**(`value`): `void` **`Experimental`** Sets the line ending at the start of the line annotation. ##### Parameters ###### value [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the line annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the line annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#source)* *** ### startPoint #### Get Signature > **get** **startPoint**(): `PdfPoint` **`Experimental`** Gets the start point of the line annotation. ##### Returns `PdfPoint` #### Set Signature > **set** **startPoint**(`value`): `void` **`Experimental`** Sets the start point of the line annotation. ##### Parameters ###### value `PdfPoint` # *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#dispose) --- ## Class: LinkAnnotation **`Experimental`** A link annotation ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) ## Constructors ### Constructor > **new LinkAnnotation**(`options`): `LinkAnnotation` **`Experimental`** Creates a new `EllipseAnnotation` instance. #### Parameters ##### options [`LinkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LinkAnnotationOptions) Options used to initialize annotation. #### Returns `LinkAnnotation` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the link annotation is clicked on ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Link` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#dispose) --- ## Abstract Class: MarkupAnnotation(Classes) Base class for all markup annotations ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) ## Extended by - [`CaretAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/CaretAnnotation) - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) - [`FileAttachmentAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/FileAttachmentAnnotation) - [`FreeTextAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/FreeTextAnnotation) - [`NoteAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/NoteAnnotation) - [`StampAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/StampAnnotation) - [`TextMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/TextMarkupAnnotation) ## Constructors ### Constructor > **new MarkupAnnotation**(`options`): `MarkupAnnotation` #### Parameters ##### options [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) #### Returns `MarkupAnnotation` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** `abstract` **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** `abstract` **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** `abstract` **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** `abstract` **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** `abstract` **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Indicates if the annotation is a widget annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#dispose) --- ## Class: NoteAnnotation(Classes) **`Experimental`** A sticky note annotation ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new NoteAnnotation**(`options`): `NoteAnnotation` **`Experimental`** Creates a new `NoteAnnotation` instance. #### Parameters ##### options [`NoteAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/NoteAnnotationOptions) Options used to initialize annotation. #### Returns `NoteAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Properties ### icon > **icon**: [`NoteAnnotationIcon`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/NoteAnnotationIcon) **`Experimental`** Icon to be displayed ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): `NoteAnnotationColor` **`Experimental`** Represents the fill color of the annotation in hexadecimal representation. ##### Returns `NoteAnnotationColor` #### Set Signature > **set** **fillColor**(`fillColor`): `void` **`Experimental`** ##### Parameters ###### fillColor `NoteAnnotationColor` # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### topLeft #### Get Signature > **get** **topLeft**(): `PdfPoint` **`Experimental`** Represents the top left point of the annotation on the page, specified as a `PdfPoint`. ##### Returns `PdfPoint` #### Set Signature > **set** **topLeft**(`topLeft`): `void` **`Experimental`** ##### Parameters ###### topLeft `PdfPoint` # *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Class: PolyLineAnnotation **`Experimental`** A poly line annotation ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) ## Constructors ### Constructor > **new PolyLineAnnotation**(`options`): `PolyLineAnnotation` **`Experimental`** Creates a new `PolyLineAnnotation` instance. #### Parameters ##### options [`PolyLineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolyLineAnnotationOptions) Options used to initialize annotation. #### Returns `PolyLineAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#dispose) --- ## Class: PolygonAnnotation **`Experimental`** An polygon drawing annotation ## Extends - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation) ## Constructors ### Constructor > **new PolygonAnnotation**(`options`): `PolygonAnnotation` **`Experimental`** Creates a new `PolygonAnnotation` instance. #### Parameters ##### options [`PolygonAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolygonAnnotationOptions) Options used to initialize annotation. #### Returns `PolygonAnnotation` *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#dispose) --- ## Class: RectangleAnnotation(Classes) **`Experimental`** A rectangle drawing annotation ## Extends - [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation) ## Constructors ### Constructor > **new RectangleAnnotation**(`options`): `RectangleAnnotation` **`Experimental`** Creates a new `RectangleAnnotation` instance. #### Parameters ##### options [`RectangleAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/RectangleAnnotationOptions) Options used to initialize annotation. #### Returns `RectangleAnnotation` *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Gets the fill color of the rectangle annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) #### Set Signature > **set** **fillColor**(`value`): `void` **`Experimental`** Sets the fill color of the rectangle annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#iswidgetannotation)* *** ### lineColor #### Get Signature > **get** **lineColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Gets the line color of the rectangle annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) #### Set Signature > **set** **lineColor**(`value`): `void` **`Experimental`** Sets the line color of the rectangle annotation. ##### Parameters ###### value [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) # *** ### lineWidth #### Get Signature > **get** **lineWidth**(): `number` **`Experimental`** Gets the line width of the rectangle annotation. ##### Returns `number` #### Set Signature > **set** **lineWidth**(`value`): `void` **`Experimental`** Sets the line width of the rectangle annotation. ##### Parameters ###### value `number` # *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`ShapeAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation#dispose) --- ## Abstract Class: ShapeAnnotation(Classes) **`Experimental`** Base class for shape annotations ## Extends - [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) ## Extended by - [`EllipseAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/EllipseAnnotation) - [`PolygonAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/PolygonAnnotation) - [`RectangleAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/RectangleAnnotation) ## Constructors ### Constructor > **new ShapeAnnotation**(`options`): `ShapeAnnotation` **`Experimental`** Creates a new `ShapeAnnotation` instance. #### Parameters ##### options [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) Options used to initialize annotation. #### Returns `ShapeAnnotation` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#constructor)* ## Properties ### stroke > **stroke**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) **`Experimental`** *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#stroke)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#subject)* *** ### type #### Get Signature > **get** `abstract` **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`DrawingAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation#dispose) --- ## Class: StampAnnotation(Classes) Base class for all stamp annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new StampAnnotation**(`options`): `StampAnnotation` Creates a new `StampAnnotation` instance. #### Parameters ##### options [`StampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/StampAnnotationOptions) Options used to initialize annotation. #### Returns `StampAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` ##### Parameters ###### content `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### data #### Get Signature > **get** **data**(): [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/type-aliases/StampData) An object representing the stamp annotation data, which depends on the subtype. ##### Returns [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/type-aliases/StampData) *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose)* *** ### rebuild() > **rebuild**(`data`): `Promise`\<`void`\> **`Experimental`** Update stamp data and rebuild the annotation while keeping history and replies. #### Parameters ##### data [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/type-aliases/StampData) #### Returns `Promise`\<`void`\> --- ## Class: TextMarkupAnnotation(Classes) **`Experimental`** Base class for text markup annotations ## Extends - [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) ## Constructors ### Constructor > **new TextMarkupAnnotation**(`options`): `TextMarkupAnnotation` **`Experimental`** Creates a new `TextMarkupAnnotation` instance. #### Parameters ##### options [`TextMarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/TextMarkupAnnotationOptions) Options used to initialize annotation. #### Returns `TextMarkupAnnotation` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#constructor)* ## Accessors ### author #### Get Signature > **get** **author**(): `string` **`Experimental`** The author. ##### Returns `string` #### Set Signature > **set** **author**(`author`): `void` **`Experimental`** ##### Parameters ###### author `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#author)* *** ### blendMode #### Get Signature > **get** **blendMode**(): [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode ##### Returns [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) #### Set Signature > **set** **blendMode**(`blendMode`): `void` **`Experimental`** ##### Parameters ###### blendMode [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#blendmode)* *** ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#content)* *** ### creationDate #### Get Signature > **get** **creationDate**(): `Date` **`Experimental`** The date and time when the annotation was created. This property retrieves the creation date from the annotation and converts it to a JavaScript Date object. ##### Returns `Date` The creation date as a JavaScript Date object, or `null` if no creation date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`creationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#creationdate)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#datemodified)* *** ### fillColor #### Get Signature > **get** **fillColor**(): [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) **`Experimental`** Retrieves the fill color used in the annotation. ##### Returns [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) The [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) representing the annotation's fill color. #### Set Signature > **set** **fillColor**(`v`): `void` **`Experimental`** Sets the fill color for the annotation. ##### Parameters ###### v [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) The new [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) to apply to the annotation. # *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#locked)* *** ### modificationDate #### Get Signature > **get** **modificationDate**(): `Date` **`Experimental`** The date and time when the annotation was last modified. This property will retrieve the modification date from the annotation and convert it to a JavaScript Date object. ##### Returns `Date` The modification date as a JavaScript Date object, or `null` if no modification date is available in the annotation. *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`modificationDate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#modificationdate)* *** ### opacity #### Get Signature > **get** **opacity**(): `number` **`Experimental`** Gets the annotation opacity. ##### Returns `number` #### Set Signature > **set** **opacity**(`o`): `void` **`Experimental`** Sets the annotation opacity. ##### Parameters ###### o `number` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#opacity)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget#source)* *** ### subject #### Get Signature > **get** **subject**(): `string` **`Experimental`** The subject. ##### Returns `string` #### Set Signature > **set** **subject**(`subject`): `void` **`Experimental`** ##### Parameters ###### subject `string` # *Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#subject)* *** ### subtype #### Get Signature > **get** **subtype**(): [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/TextMarkupType) **`Experimental`** Retrieves the type of markup applied by this annotation. ##### Returns [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/TextMarkupType) The [TextMarkupType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/TextMarkupType) representing how the text is marked, such as highlight, underline, strikethrough, squiggly, or redact. *** ### textMarkupArea #### Get Signature > **get** **textMarkupArea**(): [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\>[] **`Experimental`** Retrieves the area marked by this annotation. This represents the set of quadrilateral regions that highlight or mark portions of text within the document. ##### Returns [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\>[] An array of [Quadrilateral](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral) defining the marked-up area. *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#type)* *** ### underlyingText #### Get Signature > **get** **underlyingText**(): `string` **`Experimental`** Retrieves the text associated with the text markup annotation as a string. ##### Remarks This method provides a convenient way to access the text marked by the annotation, but it does not directly originate from the annotation object within the PDF structure. Due to potential complexities such as overlapping texts or watermarks, the returned string might not always precisely match the visually selected content. ##### Returns `string` The text associated with the annotation. ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`MarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation#dispose) --- ## Class: WatermarkAnnotation **`Experimental`** A watermark annotation ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) ## Constructors ### Constructor > **new WatermarkAnnotation**(`options`): `WatermarkAnnotation` **`Experimental`** Creates a new `WatermarkAnnotation` instance. #### Parameters ##### options [`WatermarkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WatermarkAnnotationOptions) Options used to initialize annotation. #### Returns `WatermarkAnnotation` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the watermark annotation is clicked on ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Watermark` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#dispose) --- ## Class: WidgetAnnotation **`Experimental`** A widget annotation ## Extends - [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) ## Extended by - [`ButtonWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ButtonWidget) - [`CheckBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/CheckBoxWidget) - [`ComboBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ComboBoxWidget) - [`FormWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/FormWidget) - [`ListBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ListBoxWidget) - [`RadioButtonWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/RadioButtonWidget) - [`TextBoxWidget`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget) ## Constructors ### Constructor > **new WidgetAnnotation**(`options`): `WidgetAnnotation` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `WidgetAnnotation` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Overrides [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`Annotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation#dispose) --- ## Enumeration: AnnotationLockedState(Enumerations) ## Enumeration Members ### All > **All**: `3` Fully locked, preventing deletion, modification of position and size, and changes to contents. *** ### Container > **Container**: `1` Locked to prevent modification or deletion of the annotation's position and size, excluding its contents. *** ### Content > **Content**: `2` Locked to prevent modifications to the annotation's contents, but allows changes to position and size. *** ### None > **None**: `0` No locking restrictions. --- ## Enumeration: AnnotationType(Enumerations) Annotation Type ## Enumeration Members ### 3D > **3D**: `24` *** ### Caret > **Caret**: `12` *** ### Circle > **Circle**: `8` *** ### FileAttachment > **FileAttachment**: `15` *** ### FreeText > **FreeText**: `5` *** ### Ink > **Ink**: `13` *** ### InternalLink > **InternalLink**: `3` *** ### Line > **Line**: `6` *** ### Link > **Link**: `1` *** ### Movie > **Movie**: `17` *** ### Polygon > **Polygon**: `9` *** ### PolyLine > **PolyLine**: `10` *** ### Popup > **Popup**: `14` *** ### PrinterMark > **PrinterMark**: `20` *** ### Rectangle > **Rectangle**: `7` *** ### Redact > **Redact**: `23` *** ### Screen > **Screen**: `19` *** ### Sound > **Sound**: `16` *** ### Stamp > **Stamp**: `11` *** ### Text > **Text**: `0` *** ### TextMarkup > **TextMarkup**: `4` *** ### TrapNet > **TrapNet**: `21` *** ### Watermark > **Watermark**: `22` *** ### WebLink > **WebLink**: `2` *** ### Widget > **Widget**: `18` --- ## Enumeration: FileAttachmentAnnotationIcon Specifies the type of icon displayed on a page for a . ## Enumeration Members ### CustomIcon > **CustomIcon**: `127` *** ### Graph > **Graph**: `0` *** ### Paperclip > **Paperclip**: `2` *** ### PushPin > **PushPin**: `1` *** ### Tag > **Tag**: `3` --- ## Enumeration: NoteAnnotationIcon(Enumerations) Icons for note annotation ## Enumeration Members ### Check > **Check**: `8` *** ### CheckMark > **CheckMark**: `9` *** ### Circle > **Circle**: `7` *** ### Comment > **Comment**: `0` *** ### Cross > **Cross**: `10` *** ### CrossHairs > **CrossHairs**: `11` *** ### Help > **Help**: `3` *** ### Insert > **Insert**: `6` *** ### Key > **Key**: `1` *** ### NewParagraph > **NewParagraph**: `4` *** ### Note > **Note**: `2` *** ### Paragraph > **Paragraph**: `5` *** ### RightArrow > **RightArrow**: `12` *** ### RightPointer > **RightPointer**: `13` *** ### Star > **Star**: `14` *** ### UpArrow > **UpArrow**: `15` *** ### UpLeftArrow > **UpLeftArrow**: `16` --- ## Enumeration: PredefinedTextStampType(Enumerations) An enum defining predefined text stamp types. ## Enumeration Members ### Approved > **Approved**: `0` *** ### AsIs > **AsIs**: `3` *** ### Completed > **Completed**: `14` *** ### Confidential > **Confidential**: `6` *** ### CustomStampText > **CustomStampText**: `18` *** ### Departmental > **Departmental**: `9` *** ### Draft > **Draft**: `12` *** ### Experimental > **Experimental**: `1` *** ### Expired > **Expired**: `4` *** ### Final > **Final**: `7` *** ### ForComment > **ForComment**: `10` *** ### ForPublicRelease > **ForPublicRelease**: `13` *** ### InformationOnly > **InformationOnly**: `17` *** ### NotApproved > **NotApproved**: `2` *** ### NotForPublicRelease > **NotForPublicRelease**: `5` *** ### PreliminaryResults > **PreliminaryResults**: `16` *** ### Sold > **Sold**: `8` *** ### TopSecret > **TopSecret**: `11` *** ### Void > **Void**: `15` --- ## Enumeration: StampAnnotationSubtype(Enumerations) An enum defining stamp annotation subtypes. ## Enumeration Members ### Custom > **Custom**: `4` *** ### CustomText > **CustomText**: `1` *** ### Image > **Image**: `2` *** ### Pdf > **Pdf**: `3` *** ### PredefinedText > **PredefinedText**: `0` *** ### Undefined > **Undefined**: `5` --- ## Enumeration: StampColor(Enumerations) An enum defining stamp colors. ## Enumeration Members ### Blue > **Blue**: `2` *** ### Green > **Green**: `1` *** ### Red > **Red**: `0` --- ## Enumeration: TextMarkupType(Enumerations) Enum representing different types of text markup annotations used to visually highlight or mark text. This enum differentiates the various appearances that can be applied to marked-up areas within a document, such as highlighting, underlining, striking through text, or redacting. ## Enumeration Members ### Highlight > **Highlight**: `0` Highlights the entire marked area with a background color. *** ### Redact > **Redact**: `4` Marks the entire area for redaction. *** ### Squiggly > **Squiggly**: `3` Draws a squiggly (wavy) line under the baseline of the marked text. *** ### Strikethrough > **Strikethrough**: `2` Strikes through the text with a line parallel to the baseline. *** ### Underline > **Underline**: `1` Draws a line under the baseline of the marked text. *** ### Unknown > **Unknown**: `5` Represents an uninitialized or unknown annotation type. --- ## Annotations ## Enumerations - [AnnotationLockedState](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) - [AnnotationType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) - [FileAttachmentAnnotationIcon](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/FileAttachmentAnnotationIcon) - [NoteAnnotationIcon](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/NoteAnnotationIcon) - [PredefinedTextStampType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/PredefinedTextStampType) - [StampAnnotationSubtype](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype) - [StampColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampColor) - [TextMarkupType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/TextMarkupType) ## Classes - [Annotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/Annotation) - [AnnotationRenderProperties](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) - [CaretAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/CaretAnnotation) - [DrawingAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/DrawingAnnotation) - [EllipseAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/EllipseAnnotation) - [FileAttachmentAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/FileAttachmentAnnotation) - [FreeTextAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/FreeTextAnnotation) - [InkAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/InkAnnotation) - [InternalLinkAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/InternalLinkAnnotation) - [LineAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/LineAnnotation) - [LinkAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/LinkAnnotation) - [MarkupAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/MarkupAnnotation) - [NoteAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/NoteAnnotation) - [PolygonAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/PolygonAnnotation) - [PolyLineAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/PolyLineAnnotation) - [RectangleAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/RectangleAnnotation) - [ShapeAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/ShapeAnnotation) - [StampAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/StampAnnotation) - [TextMarkupAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/TextMarkupAnnotation) - [WatermarkAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WatermarkAnnotation) - [WidgetAnnotation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Interfaces - [AnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) - [CaretAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CaretAnnotationOptions) - [CustomStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CustomStampAnnotationOptions) - [CustomTextStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CustomTextStampAnnotationOptions) - [DrawingAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) - [EllipseAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/EllipseAnnotationOptions) - [FileAttachmentAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FileAttachmentAnnotationOptions) - [FreeTextAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FreeTextAnnotationOptions) - [ImageStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ImageStampAnnotationOptions) - [InkAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InkAnnotationOptions) - [InternalLinkAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InternalLinkAnnotationOptions) - [LineAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LineAnnotationOptions) - [LinkAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LinkAnnotationOptions) - [MarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) - [NoteAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/NoteAnnotationOptions) - [PdfStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PdfStampAnnotationOptions) - [PolygonAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolygonAnnotationOptions) - [PolyLineAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolyLineAnnotationOptions) - [PredefinedTextStampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PredefinedTextStampAnnotationOptions) - [RectangleAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/RectangleAnnotationOptions) - [ShapeAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) - [StampAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/StampAnnotationOptions) - [TextMarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/TextMarkupAnnotationOptions) - [WatermarkAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WatermarkAnnotationOptions) - [WidgetAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) ## Type Aliases - [StampData](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/type-aliases/StampData) --- ## Interface: AnnotationOptions(Interfaces) Base options for all annotations ## Extended by - [`LinkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LinkAnnotationOptions) - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) - [`NoteAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/NoteAnnotationOptions) - [`WatermarkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WatermarkAnnotationOptions) - [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) - [`InternalLinkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InternalLinkAnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. --- ## Interface: CaretAnnotationOptions Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: CustomStampAnnotationOptions(Interfaces) **`Experimental`** An interface specific to Custom stamp annotations, defining custom content used for creating the annotation. ## Properties ### content > **content**: [`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent) **`Experimental`** *** ### subtype > **subtype**: [`Custom`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype#custom) **`Experimental`** --- ## Interface: CustomTextStampAnnotationOptions(Interfaces) An interface specific to custom text stamp annotations, defining the text and color. ## Properties ### color > **color**: [`StampColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampColor) *** ### subtype > **subtype**: [`CustomText`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype#customtext) *** ### text > **text**: `string` --- ## Interface: DrawingAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Extended by - [`InkAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/InkAnnotationOptions) - [`LineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/LineAnnotationOptions) - [`PolyLineAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolyLineAnnotationOptions) - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: EllipseAnnotationOptions(Interfaces) ## Extends - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#blendmode)* *** ### borderEffect? > `optional` **borderEffect?**: `BorderEffect` *** ### borderIntensity? > `optional` **borderIntensity?**: `number` *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill?**: `string` annotation fill *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`fill`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#fill)* *** ### fillColor? > `optional` **fillColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) *** ### lineColor? > `optional` **lineColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) *** ### lineWidth? > `optional` **lineWidth?**: `number` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#subject) --- ## Interface: FileAttachmentAnnotationOptions Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### icon? > `optional` **icon?**: [`FileAttachmentAnnotationIcon`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/FileAttachmentAnnotationIcon) icon #### Default Value `FileAttachmentAnnotationIcon.PushPin` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: FreeTextAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### backgroundColor? > `optional` **backgroundColor?**: `string` *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### rotation? > `optional` **rotation?**: `number` *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: ImageStampAnnotationOptions(Interfaces) An interface specific to image stamp annotations, defining the registered image used for creating the annotation. ## Properties ### image > **image**: [`PdfImage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/PdfImage) *** ### subtype > **subtype**: [`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype#image) --- ## Interface: InkAnnotationOptions Base options for all annotations ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#datemodified)* *** ### lineColor? > `optional` **lineColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) *** ### lineWidth? > `optional` **lineWidth?**: `number` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#stroke)* *** ### strokes? > `optional` **strokes?**: `PdfPoint`[][] *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: InternalLinkAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### destination > **destination**: [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. #### Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties) --- ## Interface: LineAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### color? > `optional` **color?**: [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#datemodified)* *** ### endPoint? > `optional` **endPoint?**: `PdfPoint` *** ### lineEndingAtEnd? > `optional` **lineEndingAtEnd?**: [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) *** ### lineEndingAtStart? > `optional` **lineEndingAtStart?**: [`LineEnding`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) *** ### lineWidth? > `optional` **lineWidth?**: `number` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### startPoint? > `optional` **startPoint?**: `PdfPoint` *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: LinkAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. #### Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties) --- ## Interface: MarkupAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Extended by - [`CaretAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CaretAnnotationOptions) - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) - [`FileAttachmentAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FileAttachmentAnnotationOptions) - [`FreeTextAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/FreeTextAnnotationOptions) - [`StampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/StampAnnotationOptions) - [`TextMarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/TextMarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` --- ## Interface: NoteAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### fillColor? > `optional` **fillColor?**: `NoteAnnotationColor` Represents the fill color of the annotation in hexadecimal representation. #### Default Value `"#FFECB3"` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` *** ### topLeft > **topLeft**: `PdfPoint` Represents the top left point of the annotation on the page, specified as a `PdfPoint`. #### Default Value `new Point(0, 0) as PdfPoint` --- ## Interface: PdfStampAnnotationOptions(Interfaces) An interface specific to PDF stamp annotations, defining the registered PDF content (PDF page) used for creating the annotation. ## Properties ### pdfStamp > **pdfStamp**: [`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent) *** ### subtype > **subtype**: [`Pdf`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype#pdf) --- ## Interface: PolyLineAnnotationOptions Base options for all annotations ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: PolygonAnnotationOptions ## Extends - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill?**: `string` annotation fill *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`fill`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#fill)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#subject) --- ## Interface: PredefinedTextStampAnnotationOptions(Interfaces) An interface specific to predefined text stamp annotations, defining the predefined text stamp type. ## Properties ### predefinedTextStampType > **predefinedTextStampType**: [`PredefinedTextStampType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/PredefinedTextStampType) *** ### subtype > **subtype**: [`PredefinedText`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/StampAnnotationSubtype#predefinedtext) --- ## Interface: RectangleAnnotationOptions(Interfaces) ## Extends - [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill?**: `string` annotation fill *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`fill`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#fill)* *** ### fillColor? > `optional` **fillColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) *** ### lineColor? > `optional` **lineColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) *** ### lineWidth? > `optional` **lineWidth?**: `number` *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`ShapeAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ShapeAnnotationOptions#subject) --- ## Interface: ShapeAnnotationOptions(Interfaces) ## Extends - [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions) ## Extended by - [`EllipseAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/EllipseAnnotationOptions) - [`PolygonAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PolygonAnnotationOptions) - [`RectangleAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/RectangleAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#datemodified)* *** ### fill? > `optional` **fill?**: `string` annotation fill *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#renderproperties)* *** ### stroke? > `optional` **stroke?**: [`Stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) annotation stroke *Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`stroke`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#stroke)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`DrawingAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/DrawingAnnotationOptions#subject) --- ## Interface: StampAnnotationOptions(Interfaces) Base options for all annotations ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### data > **data**: [`StampData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/type-aliases/StampData) An object representing the stamp annotation data, which depends on the subtype. *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` #### Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject) --- ## Interface: TextMarkupAnnotationOptions(Interfaces) Interface representing options for text markup annotations. This interface extends [MarkupAnnotationOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) and provides additional properties specific to text markup annotations, such as the marked area, annotation subtype, and fill color. ## Extends - [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions) ## Properties ### author? > `optional` **author?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`author`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#author)* *** ### blendMode? > `optional` **blendMode?**: [`BlendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) **`Experimental`** blend mode *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`blendMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#blendmode)* *** ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#datemodified)* *** ### fillColor? > `optional` **fillColor?**: [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) The color used to fill the marked-up area. *** ### opacity? > `optional` **opacity?**: `number` **`Experimental`** annotation opacity *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`opacity`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#opacity)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#renderproperties)* *** ### subject? > `optional` **subject?**: `string` *Inherited from [`MarkupAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions).[`subject`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/MarkupAnnotationOptions#subject)* *** ### subtype? > `optional` **subtype?**: [`TextMarkupType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/TextMarkupType) Specifies the subtype of text markup annotation. Determines how the text is visually marked, such as highlight, underline, strikethrough, squiggly, or redact. *** ### textMarkupArea? > `optional` **textMarkupArea?**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\>[] An array of quadrilateral regions defining the marked-up text area. Each quadrilateral represents a portion of the text affected by the annotation. --- ## Interface: WatermarkAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. #### Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties) --- ## Interface: WidgetAnnotationOptions Base options for all annotations ## Extends - [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions) ## Properties ### boundingBox? > `optional` **boundingBox?**: [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. #### Default Value `null` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#boundingbox)* *** ### content? > `optional` **content?**: `string` Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. #### Default Value `""` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#content)* *** ### dateModified? > `optional` **dateModified?**: `Date` The date and time when the annotation was most recently modified. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#datemodified)* *** ### page > **page**: [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) Page in which the annotation is embedded. *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#page)* *** ### privateData? > `optional` **privateData?**: `string` Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. #### Default Value `undefined` *Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#privatedata)* *** ### renderProperties? > `optional` **renderProperties?**: [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its rendering behaviors. #### Inherited from [`AnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/AnnotationOptions#renderproperties) --- ## Type Alias: StampData(Type-aliases) > **StampData** = [`PredefinedTextStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PredefinedTextStampAnnotationOptions) \| [`CustomTextStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CustomTextStampAnnotationOptions) \| [`ImageStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/ImageStampAnnotationOptions) \| [`PdfStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/PdfStampAnnotationOptions) \| [`CustomStampAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/CustomStampAnnotationOptions) A type that represents stamp data, which can be one of the specific options for different subtypes. --- ## Class: Canvas **`Experimental`** Canvas for drawing grafics and text on a PdfPage or a custom Annotation ## Constructors ### Constructor > **new Canvas**(): `Canvas` **`Experimental`** #### Returns `Canvas` ## Methods ### arcTo() > **arcTo**(): `void` **`Experimental`** *** ### beginPath() > **beginPath**(): `void` **`Experimental`** *** ### bezierCurveTo() > **bezierCurveTo**(): `void` **`Experimental`** *** ### drawText() > **drawText**(): `void` **`Experimental`** *** ### lineTo() > **lineTo**(): `void` **`Experimental`** *** ### moveTo() > **moveTo**(): `void` **`Experimental`** #### Returns `void` --- ## Class: Path **`Experimental`** ## Constructors ### Constructor > **new Path**(): `Path` **`Experimental`** #### Returns `Path` --- ## Class: PdfContentCreator **`Experimental`** PdfContentCreator is used to generate content by using operations for drawing on canvas. ## Constructors ### Constructor > **new PdfContentCreator**(`width`, `height`): `PdfContentCreator` **`Experimental`** #### Parameters ##### width `number` ##### height `number` #### Returns `PdfContentCreator` ## Methods ### beginPath() > **beginPath**(): `PdfContentCreator` **`Experimental`** #### Returns `PdfContentCreator` *** ### closePath() > **closePath**(): `PdfContentCreator` **`Experimental`** #### Returns `PdfContentCreator` *** ### drawImage() #### Call Signature > **drawImage**(`image`, `dx`, `dy`): `PdfContentCreator` **`Experimental`** ##### Parameters ###### image `Blob` ###### dx `number` ###### dy `number` ##### Returns `PdfContentCreator` #### Call Signature > **drawImage**(`image`, `dx`, `dy`, `dWidth`, `dHeight`): `PdfContentCreator` **`Experimental`** ##### Parameters ###### image `Blob` ###### dx `number` ###### dy `number` ###### dWidth `number` ###### dHeight `number` ##### Returns `PdfContentCreator` #### Call Signature > **drawImage**(`image`, `sx`, `sy`, `sWidth`, `sHeight`, `dx`, `dy`, `dWidth`, `dHeight`): `PdfContentCreator` **`Experimental`** ##### Parameters ###### image `Blob` ###### sx `number` ###### sy `number` ###### sWidth `number` ###### sHeight `number` ###### dx `number` ###### dy `number` ###### dWidth `number` ###### dHeight `number` ##### Returns `PdfContentCreator` *** ### generateContent() > **generateContent**(): [`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent) **`Experimental`** #### Returns [`PdfContent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent) *** ### lineTo() > **lineTo**(`x`, `y`): `PdfContentCreator` **`Experimental`** #### Parameters ##### x `number` ##### y `number` #### Returns `PdfContentCreator` *** ### moveTo() > **moveTo**(`x`, `y`): `PdfContentCreator` **`Experimental`** #### Parameters ##### x `number` ##### y `number` #### Returns `PdfContentCreator` *** ### rotate() > **rotate**(`deg`): `PdfContentCreator` **`Experimental`** #### Parameters ##### deg `number` #### Returns `PdfContentCreator` *** ### stroke() > **stroke**(): `PdfContentCreator` **`Experimental`** #### Returns `PdfContentCreator` --- ## Class: RgbColor(Classes) Represents a color with red, green and blue components. ## Extended by - [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`RgbColor`\> ## Constructors ### Constructor > **new RgbColor**(`colorString`): `RgbColor` Creates a new RgbColor instance from a string representation (hex, rgb or hsl). #### Parameters ##### colorString `string` The string representation of the color. #### Returns `RgbColor` #### Throws If the input string is not a valid color representation. ### Constructor > **new RgbColor**(`r?`, `g?`, `b?`): `RgbColor` Creates a new RgbColor instance. #### Parameters ##### r? `number` The red component of the color (0 to 255). ##### g? `number` The green component of the color (0 to 255). ##### b? `number` The blue component of the color (0 to 255). #### Returns `RgbColor` ## Properties ### b > **b**: `number` = `0` The blue component of the color (0 to 255). *** ### g > **g**: `number` = `0` The green component of the color (0 to 255). *** ### r > **r**: `number` = `0` The red component of the color (0 to 255). ## Accessors ### blue #### Get Signature > **get** **blue**(): `number` The intensity of blue in the described color as a value 0-255. ##### Returns `number` *** ### green #### Get Signature > **get** **green**(): `number` The intensity of green in the described color as a value 0-255. ##### Returns `number` *** ### red #### Get Signature > **get** **red**(): `number` The intensity of red in the described color as a value 0-255. ##### Returns `number` ## Methods ### clone() > **clone**(): `RgbColor` Creates a deep copy of the object. #### Returns `RgbColor` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone)* *** ### setRGB() > **setRGB**(`red`, `green`, `blue`): `void` Set a new color with all components at once #### Parameters ##### red `number` ##### green `number` ##### blue `number` *** ### toHexString() > **toHexString**(): `string` Converts the color to a hexadecimal string #### Returns `string` A string representation of the color in hexadecimal #### Example ```ts #330000 ``` *** ### toRgbaString() > **toRgbaString**(): `string` Converts the color to a CSS-formatted RGBA string. #### Returns `string` A string representation of the color in RGBA format. *** ### toRgbString() > **toRgbString**(): `string` Converts the color to a CSS-formatted RGB string. #### Returns `string` A string representation of the color in RGB format. --- ## Class: RgbaColor(Classes) Represents a color with red, green, blue, and alpha components. ## Extends - [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`RgbaColor`\> ## Constructors ### Constructor > **new RgbaColor**(`colorString`): `RgbaColor` Creates a new RgbaColor instance from a string representation (hex, rgb, rgba or hsl). #### Parameters ##### colorString `string` The string representation of the color. #### Returns `RgbaColor` #### Throws If the input string is not a valid color representation. *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#constructor)* ### Constructor > **new RgbaColor**(`r?`, `g?`, `b?`, `a?`): `RgbaColor` Creates a new RgbaColor instance. #### Parameters ##### r? `number` The red component of the color (0 to 255). ##### g? `number` The green component of the color (0 to 255). ##### b? `number` The blue component of the color (0 to 255). ##### a? `number` The alpha (transparency) component of the color (0 to 1). #### Returns `RgbaColor` *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#constructor)* ## Properties ### a > **a**: `number` The alpha component of the color (0 to 1). *** ### b > **b**: `number` = `0` The blue component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`b`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#b)* *** ### g > **g**: `number` = `0` The green component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`g`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#g)* *** ### r > **r**: `number` = `0` The red component of the color (0 to 255). *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`r`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#r)* ## Accessors ### blue #### Get Signature > **get** **blue**(): `number` The intensity of blue in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`blue`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#blue)* *** ### green #### Get Signature > **get** **green**(): `number` The intensity of green in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`green`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#green)* *** ### red #### Get Signature > **get** **red**(): `number` The intensity of red in the described color as a value 0-255. ##### Returns `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`red`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#red)* ## Methods ### clone() > **clone**(): `RgbaColor` Creates a deep copy of the object. #### Returns `RgbaColor` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone)* *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#clone)* *** ### setRGB() > **setRGB**(`red`, `green`, `blue`): `void` Set a new color with all components at once #### Parameters ##### red `number` ##### green `number` ##### blue `number` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`setRGB`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#setrgb)* *** ### toHexString() > **toHexString**(): `string` Converts the color to a hexadecimal string #### Returns `string` A string representation of the color in hexadecimal #### Example ```ts #330000 ``` *Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`toHexString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#tohexstring)* *** ### toRgbaString() > **toRgbaString**(): `string` Converts the color to a CSS-formatted RGBA string. #### Returns `string` A string representation of the color in RGBA format. *Overrides [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`toRgbaString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#torgbastring)* *** ### toRgbString() > **toRgbString**(): `string` Converts the color to a CSS-formatted RGB string. #### Returns `string` A string representation of the color in RGB format. #### Inherited from [`RgbColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor).[`toRgbString`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor#torgbstring) --- ## Class: Stroke(Classes) **`Experimental`** ## Constructors ### Constructor > **new Stroke**(): `Stroke` **`Experimental`** #### Returns `Stroke` ## Properties ### color > **color**: [`RgbaColor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) **`Experimental`** The stroke color of the stroke. If the color is transparent, no stroke is visible. *** ### dashArray > **dashArray**: `number`[] = `[]` **`Experimental`** A dash array defining a pattern of dashes and gaps to be used in drawing *** ### lineWidth > **lineWidth**: `number` = `1` **`Experimental`** The stroke width in points. If this value is 0, no stroke is drawn. #### Default Value `1` --- ## Enumeration: BlendMode(Enumerations) Blend Mode controls how new content is painted and allows the new pixels to be affected by what has already been drawn. ## Enumeration Members ### add > **add**: `5` Commonly used to create an animated lightening dissolve effect between two images. *** ### darken > **darken**: `2` Replaces only the areas that are lighter than the blend color. Areas darker than the blend color don’t change. *** ### lighten > **lighten**: `3` Replaces only pixels that are darker than the blend color. Areas lighter than the blend color don’t change. *** ### multiply > **multiply**: `1` Multiplies the base color by the blend color, resulting in darker colors. *** ### normal > **normal**: `0` Applies color normally, with no interaction with the base colors. *** ### screen > **screen**: `4` Multiplies the inverse of the blend color by the base color, resulting in a bleaching effect. *** ### subtract > **subtract**: `6` Commonly used to create an animated darkening dissolve effect between two images. --- ## Enumeration: LineEnding(Enumerations) Line ending style controls how the end of a line is painted. ## Enumeration Members ### Butt > **Butt**: `6` (PDF 1.5) A short line at the endpoint perpendicular to the line itself *** ### Circle > **Circle**: `4` A circle filled with the annotation’s interior color, if any *** ### ClosedArrow > **ClosedArrow**: `2` Two short lines meeting in an acute angle as in the OpenArrow style and connected by a third line to form a triangular closed arrowhead filled with the annotation’s interior color, if any *** ### Diamond > **Diamond**: `5` A diamond shape filled with the annotation’s interior color, if any *** ### None > **None**: `0` No line ending *** ### OpenArrow > **OpenArrow**: `1` Two short lines meeting in an acute angle to form an open arrowhead *** ### ReversedClosedArrow > **ReversedClosedArrow**: `8` (PDF 1.5) A triangular closed arrowhead in the reverse direction from ClosedArrow *** ### ReversedOpenArrow > **ReversedOpenArrow**: `7` (PDF 1.5) Two short lines in the reverse direction from OpenArrow *** ### Slash > **Slash**: `9` (PDF 1.6) A short line at the endpoint approximately 30 degrees clockwise from perpendicular to the line itself *** ### Square > **Square**: `3` A square filled with the annotation’s interior color, if any --- ## Drawing ## Namespaces - [Util](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/) ## Enumerations - [BlendMode](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/BlendMode) - [LineEnding](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/enumerations/LineEnding) ## Classes - [Canvas](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Canvas) - [Path](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Path) - [PdfContentCreator](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/PdfContentCreator) - [RgbaColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbaColor) - [RgbColor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/RgbColor) - [Stroke](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/classes/Stroke) ## Interfaces - [PdfContent](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/interfaces/PdfContent) --- ## Interface: PdfContent **`Experimental`** An interface representing PDF content. --- ## Function: drawLine() > **drawLine**(`canvas`, `p1`, `p2`, `color`): `void` Draws a line between two points on a canvas. ## Parameters ### canvas `HTMLCanvasElement` The canvas element on which to draw the line. ### p1 `DocumentViewPoint` The starting point of the line. ### p2 `DocumentViewPoint` The ending point of the line. ### color `string` The color of the line. ## Returns `void` --- ## Function: drawPoint() > **drawPoint**(`canvas`, `point`, `color`, `size`): `void` Draws a point on a canvas. ## Parameters ### canvas `HTMLCanvasElement` The canvas element on which to draw the point. ### point `DocumentViewPoint` A `DocumentViewPoint` object representing the location of the point. ### color `string` The color of the point. ### size `number` The size (radius) of the point. ## Returns `void` --- ## Function: drawQuadrilateralArea() > **drawQuadrilateralArea**(`canvas`, `quadrilateral`, `color`): `void` Draws a filled quadrilateral on a canvas. ## Parameters ### canvas `HTMLCanvasElement` The canvas element on which to draw the filled quadrilateral. ### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`DocumentViewPoint`\> A `Quadrilateral` object representing the vertices of the quadrilateral. ### color `string` The fill color of the quadrilateral. ## Returns `void` --- ## Function: drawQuadrilateralOutline() > **drawQuadrilateralOutline**(`canvas`, `quadrilateral`, `color`): `void` Draws the outline of a quadrilateral on a canvas. ## Parameters ### canvas `HTMLCanvasElement` The canvas element on which to draw the quadrilateral outline. ### quadrilateral [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`DocumentViewPoint`\> A `Quadrilateral` object representing the vertices of the quadrilateral. ### color `string` The color of the quadrilateral outline. ## Returns `void` --- ## Function: drawTextCursor() > **drawTextCursor**(`canvas`, `bottom`, `top`, `color?`, `lineWidth?`): `void` Draws a text cursor (caret) on a canvas. ## Parameters ### canvas `HTMLCanvasElement` The canvas element where the text cursor (caret) is drawn. ### bottom `DocumentViewPoint` The bottom point of the cursor line. ### top `DocumentViewPoint` The top point of the cursor line. ### color? `string` = `'#000000'` The color of the cursor (default: 'black'). ### lineWidth? `number` = `1` The width of the cursor line (default: 2). ## Returns `void` --- ## Util ## Functions - [drawLine](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/functions/drawLine) - [drawPoint](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/functions/drawPoint) - [drawQuadrilateralArea](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/functions/drawQuadrilateralArea) - [drawQuadrilateralOutline](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/functions/drawQuadrilateralOutline) - [drawTextCursor](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Drawing/namespaces/Util/functions/drawTextCursor) --- ## Class: ButtonWidget **`Experimental`** A button widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new ButtonWidget**(`options`): `ButtonWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `ButtonWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: CheckBoxWidget **`Experimental`** A checkbox widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new CheckBoxWidget**(`options`): `CheckBoxWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `CheckBoxWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: ComboBoxWidget **`Experimental`** A combo box widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new ComboBoxWidget**(`options`): `ComboBoxWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `ComboBoxWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: FormWidget **`Experimental`** A form widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new FormWidget**(`options`): `FormWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `FormWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: ListBoxWidget **`Experimental`** A list box widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new ListBoxWidget**(`options`): `ListBoxWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `ListBoxWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: RadioButtonWidget **`Experimental`** A radio button widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new RadioButtonWidget**(`options`): `RadioButtonWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `RadioButtonWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Class: TextBoxWidget **`Experimental`** A text box widget annotation ## Extends - [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation) ## Constructors ### Constructor > **new TextBoxWidget**(`options`): `TextBoxWidget` **`Experimental`** Creates a new `WidgetAnnotation` instance. #### Parameters ##### options [`WidgetAnnotationOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/interfaces/WidgetAnnotationOptions) Options used to initialize annotation. #### Returns `TextBoxWidget` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#constructor)* ## Properties ### action > **action**: [`Action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Actions/classes/Action) **`Experimental`** The action that is performed when the widget annotation is clicked on *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`action`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#action)* ## Accessors ### boundingBox #### Get Signature > **get** **boundingBox**(): [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> **`Experimental`** Represents the bounding box of the annotation, which defines its position and size on the page. The bounding box is specified as a `Rectangle` of `PdfPoint` coordinates. ##### Returns [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> #### Set Signature > **set** **boundingBox**(`rectangle`): `void` **`Experimental`** ##### Parameters ###### rectangle [`Rectangle`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle)\<`PdfPoint`\> # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`boundingBox`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#boundingbox)* *** ### content #### Get Signature > **get** **content**(): `string` **`Experimental`** Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternative description of the annotation’s contents in human-readable form. ##### Returns `string` #### Set Signature > **set** **content**(`content`): `void` **`Experimental`** ##### Parameters ###### content `string` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`content`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#content)* *** ### dateModified #### Get Signature > **get** **dateModified**(): `Date` **`Experimental`** The date and time when the annotation was most recently modified. ##### Returns `Date` #### Set Signature > **set** **dateModified**(`date`): `void` **`Experimental`** ##### Parameters ###### date `Date` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dateModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#datemodified)* *** ### hasChanges #### Get Signature > **get** **hasChanges**(): `boolean` **`Experimental`** Indicates if the annotation has been changed since the document was opened ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hasChanges`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#haschanges)* *** ### hidden #### Get Signature > **get** **hidden**(): `boolean` **`Experimental`** If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user. ##### Returns `boolean` #### Set Signature > **set** **hidden**(`hidden`): `void` **`Experimental`** ##### Parameters ###### hidden `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`hidden`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#hidden)* *** ### id #### Get Signature > **get** **id**(): `void` **`Experimental`** A unique identifier for the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#id)* *** ### interactive #### Get Signature > **get** **interactive**(): `boolean` **`Experimental`** Specifies whether the annotation allows user interaction. ##### Returns `boolean` #### Set Signature > **set** **interactive**(`interactive`): `void` **`Experimental`** ##### Parameters ###### interactive `boolean` # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`interactive`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#interactive)* *** ### isAdded #### Get Signature > **get** **isAdded**(): `boolean` **`Experimental`** Indicates whether the annotation was added to a page ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isAdded`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isadded)* *** ### isMaintainingAspectRatio #### Get Signature > **get** **isMaintainingAspectRatio**(): `boolean` **`Experimental`** Indicates if the annotation is maintaining its aspect ratio ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMaintainingAspectRatio`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismaintainingaspectratio)* *** ### isMarkupAnnotation #### Get Signature > **get** **isMarkupAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a markup annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMarkupAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismarkupannotation)* *** ### isModified #### Get Signature > **get** **isModified**(): `boolean` **`Experimental`** Indicates if the annotation has changes that have not yet been saved to the document ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isModified`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismodified)* *** ### isMoveable #### Get Signature > **get** **isMoveable**(): `boolean` **`Experimental`** Indicates if the annotation can be moved by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isMoveable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#ismoveable)* *** ### isResizable #### Get Signature > **get** **isResizable**(): `boolean` **`Experimental`** Indicates if the annotation can be resized by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isResizable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isresizable)* *** ### isRotatable #### Get Signature > **get** **isRotatable**(): `boolean` **`Experimental`** Indicates if the annotation can be rotated by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isRotatable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isrotatable)* *** ### isSelectable #### Get Signature > **get** **isSelectable**(): `boolean` **`Experimental`** Indicates if the annotation can be selected by the user ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isSelectable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#isselectable)* *** ### isWidgetAnnotation #### Get Signature > **get** **isWidgetAnnotation**(): `boolean` **`Experimental`** Indicates if the annotation is a widget annotation ##### Returns `boolean` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`isWidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#iswidgetannotation)* *** ### locked #### Get Signature > **get** **locked**(): [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) **`Experimental`** Represents the locked state of the annotation. ##### Returns [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) #### Set Signature > **set** **locked**(`locked`): `void` **`Experimental`** ##### Parameters ###### locked [`AnnotationLockedState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationLockedState) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`locked`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#locked)* *** ### page #### Get Signature > **get** **page**(): [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) **`Experimental`** Page in which the annotation is embedded. ##### Returns [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) #### Set Signature > **set** **page**(`page`): `void` **`Experimental`** Set the page in which the annotation is embedded. ##### Parameters ###### page [`Page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Page) The page to set as the annotation's page. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`page`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#page)* *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` **`Experimental`** Number of the page in which the annotation is embedded. ##### Returns `number` *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`pageNumber`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#pagenumber)* *** ### privateData #### Get Signature > **get** **privateData**(): `string` **`Experimental`** Custom data to be stored with the annotation. This can be used to store any additional information relevant to the annotation that is not covered by the standard properties. ##### Returns `string` #### Set Signature > **set** **privateData**(`privateData`): `void` **`Experimental`** ##### Parameters ###### privateData `string` Custom data to be stored with the annotation. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`privateData`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#privatedata)* *** ### renderProperties #### Get Signature > **get** **renderProperties**(): [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) **`Experimental`** Object which encapsulates the rendering properties of a PDF annotation, providing a set of flags that control its visibility, interactivity, and other rendering behaviors. ##### Returns [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) #### Set Signature > **set** **renderProperties**(`v`): `void` **`Experimental`** ##### Parameters ###### v [`AnnotationRenderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/AnnotationRenderProperties) # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`renderProperties`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#renderproperties)* *** ### source #### Get Signature > **get** **source**(): `void` **`Experimental`** Tag that identifies the source the annotation is coming from, if the source is an input PDF or an input FDF. Newly created annotations always return `null`. # *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`source`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#source)* *** ### type #### Get Signature > **get** **type**(): [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) **`Experimental`** The PDF annotation type ##### Default Value `AnnotationType.Widget` ##### Returns [`AnnotationType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/enumerations/AnnotationType) *Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`type`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#type)* ## Methods ### dispose() > **dispose**(): `void` **`Experimental`** Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. #### Inherited from [`WidgetAnnotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Annotations/classes/WidgetAnnotation#dispose) --- ## Forms ## Classes - [ButtonWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ButtonWidget) - [CheckBoxWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/CheckBoxWidget) - [ComboBoxWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ComboBoxWidget) - [FormWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/FormWidget) - [ListBoxWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/ListBoxWidget) - [RadioButtonWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/RadioButtonWidget) - [TextBoxWidget](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Forms/classes/TextBoxWidget) --- ## Class: Inset Inset in PDF Document ## Constructors ### Constructor > **new Inset**(`top`, `right`, `buttom`, `left`): `Inset` #### Parameters ##### top `number` ##### right `number` ##### buttom `number` ##### left `number` #### Returns `Inset` ## Properties ### bottom > **bottom**: `number` *** ### left > **left**: `number` *** ### right > **right**: `number` *** ### top > **top**: `number` --- ## Class: Point(Classes) Represents a point in a two-dimensional coordinate system. ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`Point`\> ## Constructors ### Constructor > **new Point**(`x?`, `y?`): `Point` Creates a new `Point` instance with the specified coordinates. #### Parameters ##### x? `number` = `0` The X value (horizontal coordinate). ##### y? `number` = `0` The Y value (vertical coordinate). #### Returns `Point` ## Properties ### x > **x**: `number` The X value (horizontal coordinate). *** ### y > **y**: `number` The Y value (vertical coordinate). ## Methods ### clone() > **clone**(): `Point` Creates a deep copy of the object. #### Returns `Point` A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone)* *** ### calculateCentroid() > `static` **calculateCentroid**(`points`): `Point` #### Parameters ##### points `Point`[] #### Returns `Point` *** ### calculateNormalLineYIntercept() > `static` **calculateNormalLineYIntercept**(`point`, `normalSlope`): `number` #### Parameters ##### point `Point` ##### normalSlope `number` #### Returns `number` *** ### calculatePerpendicularIntersection() > `static` **calculatePerpendicularIntersection**(`p1`, `p2`, `p3`): `Point` #### Parameters ##### p1 `Point` ##### p2 `Point` ##### p3 `Point` #### Returns `Point` *** ### calculateSlope() > `static` **calculateSlope**(`p1`, `p2`): `number` #### Parameters ##### p1 `Point` ##### p2 `Point` #### Returns `number` *** ### calculateYIntercept() > `static` **calculateYIntercept**(`point`, `slope`): `number` #### Parameters ##### point `Point` ##### slope `number` #### Returns `number` *** ### findIntersection() > `static` **findIntersection**(`slope1`, `yIntercept1`, `slope2`, `yIntercept2`): `Point` #### Parameters ##### slope1 `number` ##### yIntercept1 `number` ##### slope2 `number` ##### yIntercept2 `number` #### Returns `Point` --- ## Class: Quadrilateral\(Classes) # Class: Quadrilateral\ Represents a polygon with four sides and four corners. ## Type Parameters ### T `T` *extends* [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`Quadrilateral`\<`T`\>\> ## Constructors ### Constructor > **new Quadrilateral**\<`T`\>(`p1`, `p2`, `p3`, `p4`): `Quadrilateral`\<`T`\> Creates a new `Quadrilateral` instance with the specified corner coordinates. Accepts `Point` instances for each corner. #### Parameters ##### p1 `T` The Point representing the first corner. ##### p2 `T` The Point representing the second corner. ##### p3 `T` The Point representing the third corner. ##### p4 `T` The Point representing the fourth corner. #### Returns `Quadrilateral`\<`T`\> ### Constructor > **new Quadrilateral**\<`T`\>(`x1`, `y1`, `x2`, `y2`, `x3`, `y3`, `x4`, `y4`): `Quadrilateral`\<`T`\> Creates a new `Quadrilateral` instance with the specified corner coordinates. #### Parameters ##### x1 `number` The X coordinate of the first corner. ##### y1 `number` The Y coordinate of the first corner. ##### x2 `number` The X coordinate of the second corner. ##### y2 `number` The Y coordinate of the second corner. ##### x3 `number` The X coordinate of the third corner. ##### y3 `number` The Y coordinate of the third corner. ##### x4 `number` The X coordinate of the fourth corner. ##### y4 `number` The Y coordinate of the fourth corner. #### Returns `Quadrilateral`\<`T`\> ## Properties ### p1 > **p1**: `T` The `Point` representing the first corner. *** ### p2 > **p2**: `T` The `Point` representing the second corner. *** ### p3 > **p3**: `T` The `Point` representing the third corner. *** ### p4 > **p4**: `T` The `Point` representing the fourth corner. ## Accessors ### points #### Get Signature > **get** **points**(): `T`[] ##### Returns `T`[] ## Methods ### clone() > **clone**(): `Quadrilateral`\<`T`\> Creates a deep copy of the object. #### Returns `Quadrilateral`\<`T`\> A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone)* *** ### containsPoint() > **containsPoint**(`p`): `boolean` Checks if a given point is inside the quadrilateral. #### Parameters ##### p `T` The point to check, which is of type `T` extending `Point`. #### Returns `boolean` `true` if the point is inside the quadrilateral, otherwise `false`. --- ## Class: Rectangle\(Classes) # Class: Rectangle\ Represents a rectangle in a two-dimensional coordinate system. ## Type Parameters ### T `T` *extends* [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point) ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`Rectangle`\<`T`\>\> ## Constructors ### Constructor > **new Rectangle**\<`T`\>(`topLeft`, `size`): `Rectangle`\<`T`\> Creates a new `Rectangle` instance with the specified top-left corner and size. #### Parameters ##### topLeft `T` The top-left corner of the rectangle. ##### size [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The size of the rectangle. #### Returns `Rectangle`\<`T`\> ### Constructor > **new Rectangle**\<`T`\>(`x`, `y`, `width`, `height`): `Rectangle`\<`T`\> Creates a new `Rectangle` instance with the specified coordinates and dimensions. #### Parameters ##### x `number` The X coordinate of the top-left corner. ##### y `number` The Y coordinate of the top-left corner. ##### width `number` The width of the rectangle. ##### height `number` The height of the rectangle. #### Returns `Rectangle`\<`T`\> ## Properties ### size > **size**: [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The size of the rectangle. *** ### topLeft > **topLeft**: `T` The top-left corner of the rectangle. ## Accessors ### height #### Get Signature > **get** **height**(): `number` The height of the rectangle. ##### Returns `number` #### Set Signature > **set** **height**(`height`): `void` ##### Parameters ###### height `number` # *** ### width #### Get Signature > **get** **width**(): `number` The width of the rectangle. ##### Returns `number` #### Set Signature > **set** **width**(`width`): `void` ##### Parameters ###### width `number` # ## Methods ### clone() > **clone**(): `Rectangle`\<`T`\> Creates a deep copy of the object. #### Returns `Rectangle`\<`T`\> A new instance that is a deep copy of the original object. *Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone)* *** ### calculateBoundingBox() > `static` **calculateBoundingBox**(`points`): `Rectangle`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point)\> Calculates the bounding box that encompasses a given set of points. #### Parameters ##### points [`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point)[] An array of [Point](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point) objects representing the points to enclose. #### Returns `Rectangle`\<[`Point`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point)\> A Rectangle representing the bounding box of the points, or `null` if the input array is empty. #### Remarks This method determines the smallest rectangular area that fully contains all the provided points. It iterates through the points to find the minimum and maximum x and y coordinates, then constructs a Rectangle using those boundaries. If the input array is empty, the function returns `null`. --- ## Class: Size(Classes) Represents the dimensions of an object in terms of width and height. ## Implements - [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable)\<`Size`\> ## Constructors ### Constructor > **new Size**(`width?`, `height?`): `Size` Creates a new Size instance with the specified width and height. #### Parameters ##### width? `number` = `0` The width of the object. ##### height? `number` = `0` The height of the object. #### Returns `Size` ## Properties ### height > **height**: `number` The height of the object. *** ### width > **width**: `number` The width of the object. ## Methods ### clone() > **clone**(): `Size` Creates a deep copy of the object. #### Returns `Size` A new instance that is a deep copy of the original object. #### Implementation of [`Cloneable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable).[`clone`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Cloneable#clone) --- ## Enumeration: Orientation ## Enumeration Members ### landscape > **landscape**: `0` landscape orientation (width > height) *** ### portrait > **portrait**: `1` portrait orientation (height > width) *** ### square > **square**: `2` square orientation (height == width) --- ## Geometry ## Enumerations - [Orientation](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/enumerations/Orientation) ## Classes - [Inset](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Inset) - [Point](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Point) - [Quadrilateral](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral) - [Rectangle](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Rectangle) - [Size](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) ## Variables - [PaperSize](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/variables/PaperSize) --- ## Variable: PaperSize > `const` **PaperSize**: `object` predefined paper sizes ## Type Declaration ### a4\_landscape > **a4\_landscape**: `object` #### a4\_landscape.format > **format**: `string` = `'A4'` #### a4\_landscape.height > **height**: `number` = `123` #### a4\_landscape.orientation > **orientation**: [`Orientation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/enumerations/Orientation) = `Orientation.landscape` #### a4\_landscape.width > **width**: `number` = `123` ### a4\_portait > **a4\_portait**: `object` #### a4\_portait.format > **format**: `string` = `'A4'` #### a4\_portait.height > **height**: `number` = `123` #### a4\_portait.orientation > **orientation**: [`Orientation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/enumerations/Orientation) = `Orientation.portrait` #### a4\_portait.width > **width**: `number` = `123` --- ## Class: DocumentTextSearchService Service for searching text within a document. Inherits functionality from the generic SearchService class, specifying parameters for text search and returning an array of DocumentTextSearchResult objects. ## Extends - [`SearchService`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService)\<[`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams), [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> ## Constructors ### Constructor > **new DocumentTextSearchService**(`strategy`): `DocumentTextSearchService` Constructs a new SearchService instance with the specified search strategy. #### Parameters ##### strategy [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy)\<[`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams), [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> The search strategy to be used for executing search operations. #### Returns `DocumentTextSearchService` *Inherited from [`SearchService`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService#constructor)* ## Properties ### strategy > **strategy**: [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy)\<[`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams), [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> The search strategy associated with this search service. *Inherited from [`SearchService`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService).[`strategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService#strategy)* ## Methods ### execute() > **execute**(`params`): [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<[`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> Executes a search operation using the specified parameters. #### Parameters ##### params [`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams) The parameters for the search operation. #### Returns [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<[`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> A SearchExecution object representing the ongoing search operation. #### Inherited from [`SearchService`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService).[`execute`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService#execute) --- ## Class: DocumentTextSearchStrategy Represents a search strategy specifically designed for searching text within a document. Inherits functionality from the generic `SearchStrategy` class, specifying `DocumentTextSearchParams` and returning an array of `DocumentTextSearchResult` objects. ## Extends - [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy)\<[`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams), [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> ## Constructors ### Constructor > **new DocumentTextSearchStrategy**(`document`): `DocumentTextSearchStrategy` Constructs a new `DocumentTextSearchStrategy` instance. #### Parameters ##### document [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) Parameter representing the PDF document to be searched. #### Returns `DocumentTextSearchStrategy` *Overrides [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy#constructor)* ## Properties ### document > **document**: [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) The `Pdf.Document` instance associated with this search strategy. *Inherited from [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy).[`document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy#document)* ## Methods ### execute() > **execute**(`params`): [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<[`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> Executes the search strategy asynchronously. #### Parameters ##### params [`DocumentTextSearchParams`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams) The parameters for the search operation. #### Returns [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<[`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[]\> A `SearchExecution` object representing the ongoing search operation. #### Inherited from [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy).[`execute`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy#execute) --- ## Class: SearchExecution\ # Class: SearchExecution\ Event emitter for search execution events. Extends the EventEmitter class to handle events related to search execution. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\>\> ## Type Parameters ### T `T` ## Implements - `SearchExecution`\<`T`\> ## Constructors ### Constructor > **new SearchExecution**\<`T`\>(): `SearchExecution`\<`T`\> Constructs a new `SearchExecution` instance. Initializes the search execution with a Promise to track the search result. #### Returns `SearchExecution`\<`T`\> *Overrides `EventEmitter>.constructor`* ## Properties ### result > **result**: `Promise`\<`T`\> A Promise representing the result of the search execution. *Implementation of `SearchExecution.result`* *** ### state > **state**: [`SearchExecutionState`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/enumerations/SearchExecutionState) = `SearchExecutionState.Executing` The current state of the search execution. *Implementation of `SearchExecution.state`* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* keyof [`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\> A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Implementation of `SearchExecution.addEventListener`* *Inherited from `EventEmitter.addEventListener`* *** ### cancel() > **cancel**(): `void` Cancels the search execution. Sets the search execution state to "canceled" and dispatches a searchCanceled event. *Implementation of `SearchExecution.cancel`* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* keyof [`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\> A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\>\[`K`\]\> The data associated with the event. *Implementation of `SearchExecution.dispatchEvent`* *Inherited from `EventEmitter.dispatchEvent`* *** ### onErrorOccurred() > **onErrorOccurred**(`error`): `void` Handles errors that occur during the search execution. Rejects the search Promise with the error and dispatches an errorOccurred event. #### Parameters ##### error `Error` The error that occurred during the search execution. *Implementation of `SearchExecution.onErrorOccurred`* *** ### onSearchFinished() > **onSearchFinished**(`result`): `void` Handles the completion of the search execution. Sets the search execution state to "finished", resolves the search Promise with the result, and dispatches a searchFinished event. #### Parameters ##### result `T` The result of the search execution. *Implementation of `SearchExecution.onSearchFinished`* *** ### onSearchResultsFound() > **onSearchResultsFound**(`result`): `void` Handles the discovery of search results. Dispatches a searchResultsFound event. #### Parameters ##### result `T` The result of the search execution. *Implementation of `SearchExecution.onSearchResultsFound`* *** ### onSearchStarted() > **onSearchStarted**(`result`): `void` Handles the start of the search execution. Sets the search execution state to "executing" and dispatches a searchStarted event. #### Parameters ##### result `T` The result of the search execution. *Implementation of `SearchExecution.onSearchStarted`* *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* keyof [`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\> A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Implementation of `SearchExecution.removeAllListeners`* *Inherited from `EventEmitter.removeAllListeners`* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* keyof [`SearchExecutionEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap)\<`T`\> A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Implementation of `SearchExecution.removeEventListener`* #### Inherited from `EventEmitter.removeEventListener` --- ## Class: SearchService\ # Class: SearchService\ Represents a search service that facilitates executing search operations using a specified search strategy. ## Extended by - [`DocumentTextSearchService`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/DocumentTextSearchService) ## Type Parameters ### T `T` The type of parameters used for the search operation. ### K `K` The type of result returned by the search operation. ## Constructors ### Constructor > **new SearchService**\<`T`, `K`\>(`strategy`): `SearchService`\<`T`, `K`\> Constructs a new SearchService instance with the specified search strategy. #### Parameters ##### strategy [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy)\<`T`, `K`\> The search strategy to be used for executing search operations. #### Returns `SearchService`\<`T`, `K`\> ## Properties ### strategy > **strategy**: [`SearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy)\<`T`, `K`\> The search strategy associated with this search service. ## Methods ### execute() > **execute**(`params`): [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<`K`\> Executes a search operation using the specified parameters. #### Parameters ##### params `T` The parameters for the search operation. #### Returns [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<`K`\> A SearchExecution object representing the ongoing search operation. --- ## Abstract Class: SearchStrategy\ # Abstract Class: SearchStrategy\ Represents an abstract search strategy template for executing search operations. ## Extended by - [`DocumentTextSearchStrategy`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/DocumentTextSearchStrategy) ## Type Parameters ### T `T` The type of parameters used for the search operation. ### K `K` The type of result returned by the search operation. ## Constructors ### Constructor > **new SearchStrategy**\<`T`, `K`\>(): `SearchStrategy`\<`T`, `K`\> #### Returns `SearchStrategy`\<`T`, `K`\> ## Properties ### document > **document**: [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) The `Pdf.Document` instance associated with this search strategy. ## Methods ### execute() > **execute**(`params`): [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<`K`\> Executes the search strategy asynchronously. #### Parameters ##### params `T` The parameters for the search operation. #### Returns [`SearchExecution`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution)\<`K`\> A `SearchExecution` object representing the ongoing search operation. --- ## Enumeration: SearchExecutionState Enumerates different states of a search execution. Represents the current state of the search operation, such as executing, finished, canceled, or error occurred. ## Enumeration Members ### Canceled > **Canceled**: `"canceled"` The search execution has been canceled. *** ### ErrorOccurred > **ErrorOccurred**: `"error-occurred"` An error occurred during the search execution. *** ### Executing > **Executing**: `"executing"` The search execution is currently ongoing. *** ### Finished > **Finished**: `"finished"` The search execution has finished successfully. --- ## Search ## Enumerations - [SearchExecutionState](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/enumerations/SearchExecutionState) ## Classes - [DocumentTextSearchService](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/DocumentTextSearchService) - [DocumentTextSearchStrategy](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/DocumentTextSearchStrategy) - [SearchExecution](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchExecution) - [SearchService](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchService) - [SearchStrategy](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/classes/SearchStrategy) ## Interfaces - [DocumentTextSearchParams](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchParams) - [DocumentTextSearchResult](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult) - [DocumentTextSearchResultContextInfo](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResultContextInfo) - [SearchExecutionEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/SearchExecutionEventMap) --- ## Interface: DocumentTextSearchParams Represents the parameters for searching text within a document. These parameters include the search query, case sensitivity, and whether to use regular expressions. ## Properties ### caseSensitive > **caseSensitive**: `boolean` Specifies whether the search should be case-sensitive. *** ### query > **query**: `string` The search query to be used. *** ### regularExpression > **regularExpression**: `boolean` Specifies whether the search query is a regular expression. *** ### startPageNumber > **startPageNumber**: `number` Starting page for the search algorithm. --- ## Interface: DocumentTextSearchResult Represents the result of a text search within a document. Includes the matched text, context text surrounding the match, page number, and quadrilaterals outlining the position of the text on the page. ## Properties ### contextInfo > **contextInfo**: [`DocumentTextSearchResultContextInfo`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResultContextInfo) The context info containing text that surrounds matched text. *** ### pageNumber > **pageNumber**: `number` The page number where the text was found. *** ### quadrilaterals > **quadrilaterals**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\>[] Quadrilaterals outlining the position of the text on the page. *** ### text > **text**: `string` The matched text found during the search. --- ## Interface: DocumentTextSearchResultContextInfo Represents information about context text that surrounds matched text inside the document text. ## Properties ### matchEndIndex > **matchEndIndex**: `number` The match end index inside the context text. *** ### matchStartIndex > **matchStartIndex**: `number` The match start index inside the context text. *** ### text > **text**: `string` The context text surrounding the matched text. --- ## Interface: SearchExecutionEventMap\ # Interface: SearchExecutionEventMap\ Interface defining event types for `SearchExecution`. Specifies the types of events that can be emitted during a search execution. ## Type Parameters ### T `T` ## Properties ### errorOccurred > **errorOccurred**: (`error`) => `void` Event triggered when an error occurs during the search execution. #### Parameters ##### error `Error` The error that occurred during the search execution. *** ### searchCanceled > **searchCanceled**: () => `void` Event triggered when the search execution is canceled. *** ### searchFinished > **searchFinished**: (`result`) => `void` Event triggered when the search execution finishes. #### Parameters ##### result `T` The result of the search execution. *** ### searchResultsFound > **searchResultsFound**: (`result`) => `void` Event triggered when search results are found. #### Parameters ##### result `T` The result of the search execution. *** ### searchStarted > **searchStarted**: (`result`) => `void` Event triggered when the search execution starts. #### Parameters ##### result `T` The result of the search execution. #### Returns `void` --- ## Class: AccessibilityLayer Represents a layer that provides accessibility features for text fragments in a PDF document. This layer creates an invisible HTML structure that aligns with the text fragments on the page, enabling screen readers and other accessibility tools to interact with the content. ## Extends - [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<`HTMLDivElement`\> ## Constructors ### Constructor > **new AccessibilityLayer**(`id`, `documentViewPage`): `AccessibilityLayer` Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) The associated document view page. #### Returns `AccessibilityLayer` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#constructor)* ## Accessors ### documentViewPage #### Get Signature > **get** **documentViewPage**(): [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) Gets the document view page associated with this layer. ##### Returns [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`documentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#documentviewpage)* *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#id)* *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`nativeElement`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#nativeelement)* *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size to be set. # *Inherited from [`TextSelectionLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer).[`size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer#size)* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispatchevent)* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispose)* *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removeeventlistener) --- ## Class: DocumentView Class for managing the presentation and interaction with a PDF document within a container element. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap)\> ## Implements - [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable) ## Constructors ### Constructor > **new DocumentView**(`container`, `options?`): `DocumentView` Constructor for the DocumentView class. #### Parameters ##### container `HTMLElement` The container element in which the document view will be displayed. ##### options? [`DocumentViewOptions`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/DocumentViewOptions) #### Returns `DocumentView` *Overrides [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#constructor)* ## Properties ### DEFAULT\_DPI > `readonly` `static` **DEFAULT\_DPI**: `number` = `96` DPI (Dots Per Inch) - always 96 in browser context. DPI defines logical pixels per inch and is used for: - Layout calculations (page positioning, sizing) - Text sizing - Element dimensions DO NOT multiply by devicePixelRatio here. That would cause pages to appear "zoomed in" because layout calculations would use incorrect dimensions. For sharper rendering on high-DPI displays, use devicePixelRatio in RenderOptions instead (see _devicePixelRatio below). ## Accessors ### accessibilityLayerEnabled #### Get Signature > **get** **accessibilityLayerEnabled**(): `boolean` Enables or disables the accessibility layer for the document view. When enabled, the accessibility layer provides support for screen readers and other accessibility tools by creating an invisible HTML structure that aligns with the text fragments on the page. ##### Returns `boolean` #### Set Signature > **set** **accessibilityLayerEnabled**(`v`): `void` ##### Parameters ###### v `boolean` # *** ### currentPageNumber #### Get Signature > **get** **currentPageNumber**(): `number` Gets or sets the currently most visible page. ##### Returns `number` The number of the page which covers the largest area on the viewport, or `null` if the document view is not initialized. If multiple pages cover the same amount of space, the one with the smaller page number is returned. #### Set Signature > **set** **currentPageNumber**(`pageNumber`): `void` ##### Parameters ###### pageNumber `number` # *** ### devicePixelRatio #### Get Signature > **get** **devicePixelRatio**(): `number` Gets the device pixel ratio used for rendering. ##### Returns `number` *** ### firstVisiblePageNumber #### Get Signature > **get** **firstVisiblePageNumber**(): `number` Gets the page number of the first visible page in the document view. ##### Returns `number` The page number of the first visible page, or `null` if the document view is not initialized. *** ### fitMode #### Get Signature > **get** **fitMode**(): [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) **`Experimental`** Gets or sets the fit mode for the document view. ##### Returns [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) #### Set Signature > **set** **fitMode**(`fitMode`): `void` ##### Parameters ###### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) # *** ### lastVisiblePageNumber #### Get Signature > **get** **lastVisiblePageNumber**(): `number` Gets the page number of the last visible page in the document view. ##### Returns `number` The page number of the last visible page, or `null` if the document view is not initialized. *** ### pageLayoutMode #### Get Signature > **get** **pageLayoutMode**(): [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) **`Experimental`** Gets or sets the page layout mode for the document view. ##### Returns [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) #### Set Signature > **set** **pageLayoutMode**(`pageLayoutMode`): `void` ##### Parameters ###### pageLayoutMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) # *** ### pdfDocument #### Get Signature > **get** **pdfDocument**(): [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) Gets `Pdf.Document` attached to the `DocumentView`. ##### Returns [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) *** ### rotation #### Get Signature > **get** **rotation**(): [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) **`Experimental`** Gets or sets the rotation for the document view. ##### Returns [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) #### Set Signature > **set** **rotation**(`rotation`): `void` ##### Parameters ###### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) # *** ### scrollAllowance #### Get Signature > **get** **scrollAllowance**(): `ScrollAllowance` Get the current scroll allowances ##### Returns `ScrollAllowance` *** ### scrollContainer #### Get Signature > **get** **scrollContainer**(): `HTMLDivElement` Retrieves the scroll container element. The scroll container holds the individual PDF pages within the viewport. This element manages the scrolling behavior and allows navigation through different pages of the PDF document. ##### Returns `HTMLDivElement` The scroll container element. *** ### slidingWindow #### Get Signature > **get** **slidingWindow**(): `Map`\<`number`, [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage)\> Gets pages in sliding window. ##### Returns `Map`\<`number`, [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage)\> *** ### viewport #### Get Signature > **get** **viewport**(): `HTMLDivElement` Retrieves the viewport element. The viewport represents the entire document view of the PDF. It acts as the main container that defines the visible area of the PDF document. ##### Returns `HTMLDivElement` The viewport container element. *** ### zoom #### Get Signature > **get** **zoom**(): `number` Gets or sets the currently used zoom factor as a floating-point number. 1 corresponds to a zoom level of 100%. ##### Returns `number` Zoom level or null if the document view is not initialized. #### Set Signature > **set** **zoom**(`zoom`): `void` ##### Parameters ###### zoom `number` # *** ### zoomLevels #### Get Signature > **get** **zoomLevels**(): `number`[] Gets or sets the array of zoom levels available for the document view. ##### Returns `number`[] #### Set Signature > **set** **zoomLevels**(`zoomLevels`): `void` ##### Parameters ###### zoomLevels `number`[] # ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose() > **dispose**(): `void` Disposes of the object, releasing any resources it holds. The `dispose` method is responsible for performing cleanup operations and releasing any resources acquired by the object. Once an object is disposed, it should not be used, and attempts to do so may result in undefined behavior. *Implementation of [`Disposable`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/interfaces/Disposable#dispose)* *** ### goToDestination() > **goToDestination**(`destination`): `void` Navigates to the specified destination in the document view. #### Parameters ##### destination [`Destination`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/Destination) The destination to navigate to. *** ### goToPage() > **goToPage**(`pageNumber`): `any` Navigates to the specified page in the document view. #### Parameters ##### pageNumber `number` The page number to navigate to. #### Returns `any` *** ### initialize() > **initialize**(`pdfDocument`): `void` Initializes the document view. #### Parameters ##### pdfDocument [`Document`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/classes/Document) The PDF document which will be displayed inside the document view. *** ### nextPage() > **nextPage**(): `any` Navigates to the next page in the document view. #### Returns `any` *** ### previousPage() > **previousPage**(): `any` Navigates to the previous page in the document view. #### Returns `any` *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* keyof [`DocumentViewEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener) --- ## Class: DocumentViewPage Represents a page in the document view, containing multiple layers for rendering page images, search results, and interactive elements. ## Constructors ### Constructor > **new DocumentViewPage**(`documentView`, `pageNumber`): `DocumentViewPage` Creates an instance of DocumentViewPage. #### Parameters ##### documentView [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) The parent document view. ##### pageNumber `number` The page number. #### Returns `DocumentViewPage` ## Accessors ### accessibilityLayer #### Get Signature > **get** **accessibilityLayer**(): [`AccessibilityLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/AccessibilityLayer) Retrieves the accessibility layer. This layer contains invisible HTML elements aligned with the text fragments for accessibility purposes. ##### Returns [`AccessibilityLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/AccessibilityLayer) *** ### container #### Get Signature > **get** **container**(): `HTMLDivElement` Gets the container element. ##### Returns `HTMLDivElement` *** ### documentView #### Get Signature > **get** **documentView**(): [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) Gets the associated document view. ##### Returns [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) *** ### image #### Set Signature > **set** **image**(`v`): `void` Sets the page image data for the page and updates the image layer. ##### Parameters ###### v [`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Image) The new image data. # *** ### interactiveLayers #### Get Signature > **get** **interactiveLayers**(): [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<[`LayerNativeElementType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/LayerNativeElementType)\>[] Gets the array of interactive layers. ##### Returns [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<[`LayerNativeElementType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/LayerNativeElementType)\>[] #### Set Signature > **set** **interactiveLayers**(`v`): `void` Sets the interactive layers, updating their placement within the container. Each layer's size is updated to match the page size and the container is refreshed to maintain the correct layer stacking order. ##### Parameters ###### v [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<[`LayerNativeElementType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/LayerNativeElementType)\>[] # *** ### origin #### Get Signature > **get** **origin**(): `DocumentViewPoint` Gets the origin point of the page. ##### Returns `DocumentViewPoint` #### Set Signature > **set** **origin**(`v`): `void` Sets the origin of the page and updates its position within the document view. ##### Parameters ###### v `DocumentViewPoint` The new origin point. # *** ### pageImageLayer #### Get Signature > **get** **pageImageLayer**(): [`PageImageLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/PageImageLayer) Gets the page image layer. ##### Returns [`PageImageLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/PageImageLayer) *** ### pageNumber #### Get Signature > **get** **pageNumber**(): `number` Gets the page number. ##### Returns `number` *** ### searchResultsLayer #### Get Signature > **get** **searchResultsLayer**(): [`SearchResultsLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/SearchResultsLayer) Gets the search results layer. ##### Returns [`SearchResultsLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/SearchResultsLayer) #### Set Signature > **set** **searchResultsLayer**(`v`): `void` Sets the search results layer and updates its size. ##### Parameters ###### v [`SearchResultsLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/SearchResultsLayer) # *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the page. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the page and updates the dimensions of associated layers. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size of the page. # ## Methods ### appendAllLayers() > **appendAllLayers**(): `void` Appends the various layers (page image, search results, interactive, and accessibility layers) to the container element of the document view page. This method ensures that the layers are added in the correct order: 1. The page image layer is added first, as it serves as the base layer. 2. The search results layer is added on top of the page image layer. 3. The interactive layers, if present, are added next to handle user interactions. 4. The accessibility layer, if enabled, is added last to provide accessibility features. *** ### dispose() > **dispose**(): `void` Disposes of the document view page and all its layers. This method calls dispose on all layers to allow them to clean up resources, remove event listeners, or perform any necessary cleanup operations. #### Returns `void` --- ## Abstract Class: Layer\(Classes) # Abstract Class: Layer\ Abstract base class for a Layer, which is an event emitter that renders on a native HTML element. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\> ## Extended by - [`PageImageLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/PageImageLayer) - [`SearchResultsLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/SearchResultsLayer) - [`AccessibilityLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/AccessibilityLayer) - [`TextSelectionLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer) ## Type Parameters ### T `T` *extends* [`LayerNativeElementType`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/LayerNativeElementType) The type of the native element, either `HTMLDivElement` or `HTMLCanvasElement`. ## Constructors ### Constructor > **new Layer**\<`T`\>(`id`, `documentViewPage`): `Layer`\<`T`\> Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) The associated document view page. #### Returns `Layer`\<`T`\> *Overrides [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#constructor)* ## Accessors ### documentViewPage #### Get Signature > **get** **documentViewPage**(): [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) Gets the document view page associated with this layer. ##### Returns [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size to be set. # ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener) --- ## Class: PageImageLayer Represents a layer that renders an page image on a canvas. ## Extends - [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<`HTMLCanvasElement`\> ## Constructors ### Constructor > **new PageImageLayer**(`id`, `documentViewPage`): `PageImageLayer` Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) The associated document view page. #### Returns `PageImageLayer` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#constructor)* ## Accessors ### documentViewPage #### Get Signature > **get** **documentViewPage**(): [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) Gets the document view page associated with this layer. ##### Returns [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`documentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#documentviewpage)* *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#id)* *** ### image #### Set Signature > **set** **image**(`v`): `void` Sets the page image data and triggers rendering. ##### Parameters ###### v [`Image`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Image) The new image data. # *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`nativeElement`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#nativeelement)* *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size to be set. # *Inherited from [`TextSelectionLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer).[`size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer#size)* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispatchevent)* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispose)* *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removeeventlistener) --- ## Class: PluginManager Manages a collection of plugins, allowing registration, activation, and deactivation. ## Constructors ### Constructor > **new PluginManager**(): `PluginManager` #### Returns `PluginManager` ## Accessors ### documentView #### Get Signature > **get** **documentView**(): [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) Gets the current document view. ##### Returns [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) #### Set Signature > **set** **documentView**(`v`): `void` Sets a new document view and updates all registered plugins with the new view. Deactivates each plugin before assigning the new view. ##### Parameters ###### v [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) # ## Methods ### activatePlugin() > **activatePlugin**(`plugin`): `void` Activates a given plugin and deactivates all other plugins. #### Parameters ##### plugin [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) The plugin to activate. *** ### activatePluginById() > **activatePluginById**(`pluginId`): `void` Activates a plugin by its ID and deactivates all other plugins. #### Parameters ##### pluginId `string` The ID of the plugin to activate. #### Throws If the plugin with the given ID does not exist. *** ### deregisterPlugin() > **deregisterPlugin**(`plugin`): `void` Deregisters a plugin and deactivates it. #### Parameters ##### plugin [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) The plugin to deregister. *** ### deregisterPluginById() > **deregisterPluginById**(`pluginId`): `void` Deregisters a plugin by its ID. #### Parameters ##### pluginId `string` The ID of the plugin to deregister. #### Throws If the plugin with the given ID does not exist. *** ### getPluginById() > **getPluginById**(`id`): [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) Retrieves a plugin by its ID. #### Parameters ##### id `string` The ID of the plugin to retrieve. #### Returns [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) The plugin with the given ID, or undefined if not found. *** ### registerPlugin() > **registerPlugin**(`plugin`): `void` Registers a new plugin. #### Parameters ##### plugin [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) The plugin to register. #### Throws If a plugin with the same ID is already registered. --- ## Class: SearchResultsLayer Represents a layer that highlights search results on a PDF document. ## Extends - [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<`HTMLCanvasElement`\> ## Constructors ### Constructor > **new SearchResultsLayer**(`id`, `documentViewPage`): `SearchResultsLayer` Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) The associated document view page. #### Returns `SearchResultsLayer` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#constructor)* ## Accessors ### activeSearchResult #### Set Signature > **set** **activeSearchResult**(`v`): `void` Sets the active search result and triggers rendering. ##### Parameters ###### v [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult) The active search result. # *** ### documentViewPage #### Get Signature > **get** **documentViewPage**(): [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) Gets the document view page associated with this layer. ##### Returns [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`documentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#documentviewpage)* *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#id)* *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`nativeElement`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#nativeelement)* *** ### searchResults #### Set Signature > **set** **searchResults**(`v`): `void` Sets the search results and triggers rendering. ##### Parameters ###### v [`DocumentTextSearchResult`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Search/interfaces/DocumentTextSearchResult)[] The new search results. # *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size to be set. # *Inherited from [`TextSelectionLayer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer).[`size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer#size)* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispatchevent)* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispose)* *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removeeventlistener) --- ## Class: TextSelectionLayer Abstract base class for a Layer, which is an event emitter that renders on a native HTML element. ## Extends - [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer)\<`HTMLCanvasElement`\> ## Constructors ### Constructor > **new TextSelectionLayer**(`id`, `documentViewPage`): `TextSelectionLayer` Creates an instance of Layer. #### Parameters ##### id `string` The unique identifier for the layer. ##### documentViewPage [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) The associated document view page. #### Returns `TextSelectionLayer` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#constructor)* ## Accessors ### documentViewPage #### Get Signature > **get** **documentViewPage**(): [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) Gets the document view page associated with this layer. ##### Returns [`DocumentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`documentViewPage`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#documentviewpage)* *** ### id #### Get Signature > **get** **id**(): `string` Gets the unique identifier of the layer. ##### Returns `string` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#id)* *** ### nativeElement #### Get Signature > **get** **nativeElement**(): `T` Gets the native HTML element of this layer. ##### Returns `T` *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`nativeElement`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#nativeelement)* *** ### size #### Get Signature > **get** **size**(): [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) Gets the size of the layer. ##### Returns [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) #### Set Signature > **set** **size**(`v`): `void` Sets the size of the layer and dispatches a size change event if the size is different. ##### Parameters ###### v [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size to be set. # *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#size)* ## Methods ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#addeventlistener)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`LayerEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispatchevent)* *** ### dispose()? > `optional` **dispose**(): `void` Optional cleanup method called when the layer is about to be removed. Override this method to release resources, remove event listeners, or perform any necessary cleanup. The PDF Web SDK calls this method automatically when a page is removed from the viewport. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`dispose`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#dispose)* *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* `"sizeChanged"` A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. #### Inherited from [`Layer`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer#removeeventlistener) --- ## Class: TextSelectionPlugin Represents a plugin that can be registered, activated, and deactivated. ## Extends - [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter)\<[`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap)\> ## Implements - [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) ## Constructors ### Constructor > **new TextSelectionPlugin**(`documentView`): `TextSelectionPlugin` #### Parameters ##### documentView [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) #### Returns `TextSelectionPlugin` *Overrides [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`constructor`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#constructor)* ## Properties ### id > **id**: `string` = `'text-selection-plugin'` Unique identifier for the plugin. *Implementation of [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin).[`id`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin#id)* ## Accessors ### active #### Get Signature > **get** **active**(): `boolean` ##### Returns `boolean` #### Set Signature > **set** **active**(`v`): `void` ##### Parameters ###### v `boolean` # *** ### cursorPosition #### Get Signature > **get** **cursorPosition**(): [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) ##### Returns [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) *** ### debugMode #### Get Signature > **get** **debugMode**(): `boolean` ##### Returns `boolean` #### Set Signature > **set** **debugMode**(`v`): `void` ##### Parameters ###### v `boolean` # *** ### documentView #### Get Signature > **get** **documentView**(): [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) The document view associated with the plugin. ##### Returns [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) #### Set Signature > **set** **documentView**(`v`): `void` The document view associated with the plugin. ##### Parameters ###### v [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) # The document view associated with the plugin. *Implementation of [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin).[`documentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin#documentview)* *** ### selectionColor #### Get Signature > **get** **selectionColor**(): `string` ##### Returns `string` #### Set Signature > **set** **selectionColor**(`v`): `void` ##### Parameters ###### v `string` # ## Methods ### activate() > **activate**(): `void` Activates the plugin. *Implementation of [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin).[`activate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin#activate)* *** ### addEventListener() > **addEventListener**\<`K`\>(`type`, `listener`): `void` Register a function that will be called whenever the specified event is delivered. #### Type Parameters ##### K `K` *extends* keyof [`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to listen for. ##### listener (...`e`) => `void` The function that will be executed when an event of the specified type occurs. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`addEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#addeventlistener)* *** ### clearSelection() > **clearSelection**(): `void` Clears the current text selection. *** ### deactivate() > **deactivate**(): `void` Deactivates the plugin. *Implementation of [`Plugin`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin).[`deactivate`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin#deactivate)* *** ### dispatchEvent() > **dispatchEvent**\<`K`\>(`type`, `args`): `void` Dispatches an event to all registered listeners. #### Type Parameters ##### K `K` *extends* keyof [`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event type to dispatch. ##### args `Parameters`\<[`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap)\[`K`\]\> The data associated with the event. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`dispatchEvent`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#dispatchevent)* *** ### getCursorGeometry() > **getCursorGeometry**(`position`): `Promise`\<[`CursorGeometry`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorGeometry)\> Gets the geometry of a cursor at a given position for rendering. This geometry specifies the cursor's position using the top coordinate, bottom coordinate, and a page number. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The cursor position to retrieve geometry. This geometry specifies the cursor's position using the top coordinate, bottom coordinate, and a page number. #### Returns `Promise`\<[`CursorGeometry`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorGeometry)\> The cursor geometry or `null` if the position is invalid. *** ### getNextPosition() > **getNextPosition**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the next cursor position (one glyph to the right). #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The next position, or null if at the end of the document. This method is experimental and may change in future versions. *** ### getNextWordPosition() > **getNextWordPosition**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the cursor position at the start of the next word. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The next word position, or `null` if at end of document. This method is experimental and may change in future versions. *** ### getPositionAbove() > **getPositionAbove**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the cursor position one line above (visually) while maintaining the horizontal position as closely as possible. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The position above, or null if at the top of the document. This method is experimental and may change in future versions. *** ### getPositionBelow() > **getPositionBelow**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the cursor position one line below (visually) while maintaining the horizontal position as closely as possible. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The position below, or null if at the bottom of the document. This method is experimental and may change in future versions. *** ### getPreviousPosition() > **getPreviousPosition**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the previous cursor position (one glyph to the left). #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The previous position, or null if at the start of the document. This method is experimental and may change in future versions. *** ### getPreviousWordPosition() > **getPreviousWordPosition**(`position`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Calculates the cursor position at the start of the previous word. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The current cursor position. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The previous word position, or `null` if at start of document. This method is experimental and may change in future versions. *** ### getSelection() > **getSelection**(): [`TextSelection`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelection) Gets the current text selection with geometry information. Useful for creating annotations or positioning UI elements. #### Returns [`TextSelection`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelection) The current selection or null if nothing selected. *** ### getTextFragments() > **getTextFragments**(`pageNumber`): `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> Gets the text fragments for a given page. Useful for implementing custom cursor navigation logic. #### Parameters ##### pageNumber `number` The page number to get fragments for. #### Returns `Promise`\<[`TextFragment`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/interfaces/TextFragment)[]\> Array of text fragments on the page. *** ### removeAllListeners() > **removeAllListeners**\<`K`\>(`type`): `void` Remove all listeners for a given event. #### Type Parameters ##### K `K` *extends* keyof [`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove all listeners. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeAllListeners`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removealllisteners)* *** ### removeEventListener() > **removeEventListener**\<`K`\>(`type`, `listener`): `void` Removes an event listener previously registered with addEventListener. #### Type Parameters ##### K `K` *extends* keyof [`TextSelectionPluginEventMap`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap) A generic type representing the key of the event type. #### Parameters ##### type `K` String representing the event for which to remove an event listener. ##### listener (...`e`) => `void` The event listener function of the event handler to remove from the event target. *Inherited from [`EventEmitter`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter).[`removeEventListener`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/classes/EventEmitter#removeeventlistener)* *** ### selectToNextWord() > **selectToNextWord**(`anchor`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Extends the selection from the anchor position to the next word. Useful for implementing Shift+Ctrl+Right keyboard navigation. #### Parameters ##### anchor [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The anchor position where the selection started. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The new cursor position, or `null` if at end of document. This method is experimental and may change in future versions. *** ### selectToPreviousWord() > **selectToPreviousWord**(`anchor`): `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> **`Experimental`** Extends the selection from the anchor position to the previous word. Useful for implementing Shift+Ctrl+Left keyboard navigation. #### Parameters ##### anchor [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The anchor position where the selection started. #### Returns `Promise`\<[`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition)\> The new cursor position, or `null` if at start of document. This method is experimental and may change in future versions. *** ### setCursorPosition() > **setCursorPosition**(`position`): `Promise`\<`void`\> Sets the cursor position programmatically. Useful for restoring a previously saved cursor position. #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The cursor position to set, or `null` to remove the cursor. #### Returns `Promise`\<`void`\> *** ### setSelectionRange() > **setSelectionRange**(`anchor`, `cursor`): `Promise`\<`void`\> Sets the text selection between two cursor positions. Useful for implementing keyboard-based text selection (Shift+Arrow). #### Parameters ##### anchor [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The anchor position where the selection started. ##### cursor [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) The cursor position where the selection currently ends. #### Returns `Promise`\<`void`\> --- ## Function: drawTextSelectionInfo() > **drawTextSelectionInfo**(`documentView`, `textSelectionInfo`, `debugMode?`, `selectionColor?`): `void` ## Parameters ### documentView [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) ### textSelectionInfo `TextSelectionInfo` ### debugMode? `boolean` = `false` ### selectionColor? `string` = `DEFAULT_SELECTION_COLOR` ## Returns `void` --- ## Function: drawTextSelectionInfoDebug() > **drawTextSelectionInfoDebug**(`documentView`, `textSelectionInfo`): `void` ## Parameters ### documentView [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) ### textSelectionInfo `TextSelectionInfo` ## Returns `void` --- ## UI ## Classes - [AccessibilityLayer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/AccessibilityLayer) - [DocumentView](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) - [DocumentViewPage](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentViewPage) - [Layer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/Layer) - [PageImageLayer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/PageImageLayer) - [PluginManager](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/PluginManager) - [SearchResultsLayer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/SearchResultsLayer) - [TextSelectionLayer](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionLayer) - [TextSelectionPlugin](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/TextSelectionPlugin) ## Interfaces - [CursorGeometry](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorGeometry) - [CursorPosition](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) - [DocumentViewEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/DocumentViewEventMap) - [Image](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Image) - [LayerEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/LayerEventMap) - [Plugin](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/Plugin) - [SelectionQuadrilateral](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/SelectionQuadrilateral) - [TextSelection](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelection) - [TextSelectionPluginEventMap](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelectionPluginEventMap) ## Type Aliases - [DocumentViewOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/DocumentViewOptions) - [LayerNativeElementType](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/type-aliases/LayerNativeElementType) ## Functions - [drawTextSelectionInfo](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/functions/drawTextSelectionInfo) - [drawTextSelectionInfoDebug](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/functions/drawTextSelectionInfoDebug) --- ## Interface: CursorGeometry Represents the geometry of a cursor for rendering. ## Properties ### bottom > **bottom**: `object` The bottom point of the cursor line in document view coordinates. #### x > **x**: `number` #### y > **y**: `number` *** ### pageNumber > **pageNumber**: `number` The page number where the cursor is located. *** ### top > **top**: `object` The top point of the cursor line in document view coordinates. #### x > **x**: `number` #### y > **y**: `number` --- ## Interface: CursorPosition Defines the position of the text cursor within the document. ## Properties ### fragmentIndex > **fragmentIndex**: `number` The index of the text fragment containing the cursor. *** ### glyphOffsetIndex > **glyphOffsetIndex**: `number` The index of the glyph offset within the text fragment. *** ### pageNumber > **pageNumber**: `number` The page number where the cursor is located. --- ## Interface: DocumentViewEventMap Interface defining event types for changes in a document view. ## Properties ### currentPageChanged > **currentPageChanged**: (`pageNumber`) => `void` Event triggered when the currently displayed page in the document view changes. The event payload is a number representing the page number of the currently displayed page. #### Parameters ##### pageNumber `number` *** ### documentViewClick > **documentViewClick**: (`payload`) => `void` Event triggered when the document view is clicked. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewDoubleClick > **documentViewDoubleClick**: (`payload`) => `void` Event triggered when the document view is double-clicked. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewMouseDown > **documentViewMouseDown**: (`payload`) => `void` Event triggered when the mouse button is pressed down within the document view. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewMouseEnter > **documentViewMouseEnter**: (`payload`) => `void` Event triggered when the mouse enters the document view. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewMouseLeave > **documentViewMouseLeave**: (`payload`) => `void` Event triggered when the mouse leaves the document view. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewMouseMove > **documentViewMouseMove**: (`payload`) => `void` Event triggered when the mouse moves within the document view. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewMouseUp > **documentViewMouseUp**: (`payload`) => `void` Event triggered when the mouse button is released within the document view. The event payload is the MouseEvent object. #### Parameters ##### payload `MouseEvent` *** ### documentViewPointerCancel > **documentViewPointerCancel**: (`event`) => `void` Fired when a pointer is canceled (e.g. touch→pointercancel) in the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewPointerDown > **documentViewPointerDown**: (`event`) => `void` Fired when a pointer is pressed down anywhere in the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewPointerEnter > **documentViewPointerEnter**: (`event`) => `void` Fired when a pointer enters the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewPointerLeave > **documentViewPointerLeave**: (`event`) => `void` Fired when a pointer leaves the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewPointerMove > **documentViewPointerMove**: (`event`) => `void` Fired when a pointer moves within the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewPointerUp > **documentViewPointerUp**: (`event`) => `void` Fired when a pointer is released anywhere in the document view. #### Parameters ##### event `PointerEvent` *** ### documentViewTouchCancel > **documentViewTouchCancel**: (`payload`) => `void` Event triggered when a touch is canceled within the document view. The event payload is the TouchEvent object. #### Parameters ##### payload `TouchEvent` *** ### documentViewTouchEnd > **documentViewTouchEnd**: (`payload`) => `void` Event triggered when a touch ends within the document view. The event payload is the TouchEvent object. #### Parameters ##### payload `TouchEvent` *** ### documentViewTouchMove > **documentViewTouchMove**: (`payload`) => `void` Event triggered when a touch moves within the document view. The event payload is the TouchEvent object. #### Parameters ##### payload `TouchEvent` *** ### documentViewTouchStart > **documentViewTouchStart**: (`payload`) => `void` Event triggered when a touch starts within the document view. The event payload is the TouchEvent object. #### Parameters ##### payload `TouchEvent` *** ### firstVisiblePageChanged > **firstVisiblePageChanged**: (`pageNumber`) => `void` Event triggered when the index of the first visible page in the document view changes. The event payload is a number representing the page number of the first visible page. #### Parameters ##### pageNumber `number` *** ### fitModeChanged > **fitModeChanged**: (`fitMode`) => `void` Event triggered when the fit mode of the document view changes. The event payload is a value of the FitMode enum representing the new fit mode. #### Parameters ##### fitMode [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) *** ### lastVisiblePageChanged > **lastVisiblePageChanged**: (`pageNumber`) => `void` Event triggered when the index of the last visible page in the document view changes. The event payload is a number representing the page number of the last visible page. #### Parameters ##### pageNumber `number` *** ### pageAddedToViewport > **pageAddedToViewport**: (`pageNumber`) => `void` #### Parameters ##### pageNumber `number` *** ### pageClick > **pageClick**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageDoubleClick > **pageDoubleClick**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageLayoutModeChanged > **pageLayoutModeChanged**: (`pageLayoutMode`) => `void` Event triggered when the page layout mode of the document view changes. The event payload is a value of the PageLayoutMode enum representing the new layout mode. #### Parameters ##### pageLayoutMode [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) *** ### pageMouseDown > **pageMouseDown**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageMouseEnter > **pageMouseEnter**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageMouseLeave > **pageMouseLeave**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageMouseMove > **pageMouseMove**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pageMouseUp > **pageMouseUp**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `MouseEvent` *** ### pagePointerCancel > **pagePointerCancel**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pagePointerDown > **pagePointerDown**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pagePointerEnter > **pagePointerEnter**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pagePointerLeave > **pagePointerLeave**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pagePointerMove > **pagePointerMove**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pagePointerUp > **pagePointerUp**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `PointerEvent` *** ### pageRemovedFromViewport > **pageRemovedFromViewport**: (`pageNumber`) => `void` #### Parameters ##### pageNumber `number` *** ### pageRendered > **pageRendered**: (`pageNumber`) => `void` Event triggered when a page in the document view finishes rendering. The event payload is a number representing the page number of the rendered page. #### Parameters ##### pageNumber `number` *** ### pageTouchCancel > **pageTouchCancel**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `TouchEvent` *** ### pageTouchEnd > **pageTouchEnd**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `TouchEvent` *** ### pageTouchMove > **pageTouchMove**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `TouchEvent` *** ### pageTouchStart > **pageTouchStart**: (`pageNumber`, `payload`) => `void` #### Parameters ##### pageNumber `number` ##### payload `TouchEvent` *** ### rotationChanged > **rotationChanged**: (`rotation`) => `void` Event triggered when the rotation of the document view changes. The event payload is a value of the Rotation enum representing the new rotation. #### Parameters ##### rotation [`Rotation`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/Rotation) *** ### scrollPositionChanged > **scrollPositionChanged**: (`x`, `y`) => `void` Event triggered when the scroll in the document view changes. The event payload is the x,y coordinates of the new scroll position. #### Parameters ##### x `number` ##### y `number` *** ### zoomChanged > **zoomChanged**: (`zoomLevel`) => `void` Event triggered when the zoom level of the document view changes. The event payload is a number representing the new zoom level. #### Parameters ##### zoomLevel `number` #### Returns `void` --- ## Interface: Image Interface representing the image provided by the PDF renderer. The image contains a pixel buffer and dimensions. On high-DPI displays, the buffer contains more pixels than the logical dimensions indicate. To determine the effective DPR (device pixel ratio) used for rendering, compute it from the buffer size relative to the logical dimensions: ``` const dpr = Math.sqrt(buffer.byteLength / (width * height * 4)); ``` Example: A 500x500 logical image rendered at DPR 2 has: - Logical size: 500x500 (used for layout/positioning) - Buffer size: 1000x1000 pixels (used for sharp rendering) - Buffer length: 1000 * 1000 * 4 = 4,000,000 bytes (RGBA) - Computed DPR: Math.sqrt(4000000 / (500 * 500 * 4)) = 2 ## Properties ### buffer > **buffer**: `ArrayBuffer` Raw RGBA pixel data. Size = (width * dpr) * (height * dpr) * 4 bytes. *** ### height > **height**: `number` Height in logical pixels (used for layout/positioning, unaffected by DPR). *** ### width > **width**: `number` Width in logical pixels (used for layout/positioning, unaffected by DPR). --- ## Interface: LayerEventMap Defines the event map for the Layer class. ## Properties ### sizeChanged > **sizeChanged**: (`size`) => `void` Event triggered when the layer size changes. #### Parameters ##### size [`Size`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Size) The new size of the layer. #### Returns `void` --- ## Interface: Plugin(Interfaces) Represents a plugin that can be registered, activated, and deactivated. ## Properties ### documentView > **documentView**: [`DocumentView`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/classes/DocumentView) The document view associated with the plugin. *** ### id > **id**: `string` Unique identifier for the plugin. ## Methods ### activate() > **activate**(): `void` Activates the plugin. *** ### deactivate() > **deactivate**(): `void` Deactivates the plugin. #### Returns `void` --- ## Interface: SelectionQuadrilateral Represents a quadrilateral with its associated page number. ## Properties ### pageNumber > **pageNumber**: `number` The page number where the quadrilateral is located. *** ### quadrilateral > **quadrilateral**: [`Quadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/namespaces/Geometry/classes/Quadrilateral)\<`PdfPoint`\> The quadrilateral geometry. --- ## Interface: TextSelection Represents the current text selection with geometry information. ## Properties ### endPageNumber > **endPageNumber**: `number` The page number where the selection ends. *** ### quadrilaterals > **quadrilaterals**: [`SelectionQuadrilateral`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/SelectionQuadrilateral)[] Array of quadrilaterals representing the selection areas. *** ### startPageNumber > **startPageNumber**: `number` The page number where the selection starts. *** ### text > **text**: `string` The selected text content. --- ## Interface: TextSelectionPluginEventMap Interface defining event types for changes in a document view. ## Properties ### cursorPositionChanged > **cursorPositionChanged**: (`position`) => `void` #### Parameters ##### position [`CursorPosition`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/CursorPosition) *** ### keyDown > **keyDown**: (`event`) => `void` #### Parameters ##### event `KeyboardEvent` *** ### textSelectionChanged > **textSelectionChanged**: (`textSelectionData`) => `void` #### Parameters ##### textSelectionData [`TextSelection`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/interfaces/TextSelection) #### Returns `void` --- ## Type Alias: DocumentViewOptions > **DocumentViewOptions** = `object` Configuration options for initializing a `DocumentView`. These options allow you to customize the initial behavior and appearance of the document view. ## Properties ### accessibilityLayerEnabled? > `optional` **accessibilityLayerEnabled?**: `boolean` Enables or disables the accessibility layer for the document view. When enabled, the accessibility layer provides support for screen readers and other accessibility tools by creating an invisible HTML structure aligned with the text fragments on the page. #### Default Value `false` *** ### devicePixelRatio? > `optional` **devicePixelRatio?**: `number` Device pixel ratio (DPR) for rendering. Higher values produce sharper images at the cost of more memory and CPU usage. #### Default Value `window.devicePixelRatio` *** ### fitMode? > `optional` **fitMode?**: [`FitMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/FitMode) Specifies the fit mode for the document view. Determines how the document pages are scaled to fit within the viewport. #### Default Value `FitMode.None` *** ### pageLayoutMode? > `optional` **pageLayoutMode?**: [`PageLayoutMode`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/enumerations/PageLayoutMode) Specifies the page layout mode for the document view. Determines how pages are arranged within the viewport (e.g., single column, two columns). #### Default Value `PageLayoutMode.OneColumn` *** ### useInitialDestination? > `optional` **useInitialDestination?**: `boolean` Controls whether to automatically navigate to the PDF's initial destination when the document view is initialized. If the PDF does not have an initial destination, this option has no effect. #### Default Value `true` --- ## Type Alias: LayerNativeElementType > **LayerNativeElementType** = `HTMLDivElement` \| `HTMLCanvasElement` Represents the native element types that a Layer can use. --- ## Enumeration: LicenseFeature Specifies functional features which are supported by the PDF Web SDK. A given license key can permit or prohibit any of these features. ## Enumeration Members ### All > **All**: `15` All features *** ### Annotate > **Annotate**: `1` Create and edit annotations *** ### ContentEditing > **ContentEditing**: `8` Allow content editing *** ### FillFormFields > **FillFormFields**: `2` Fill out form fields *** ### PageAssembly > **PageAssembly**: `4` Allow page assembly --- ## @pdftools/pdf-web-sdk ## Namespaces - [Core](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/) - [Pdf](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Pdf/) - [UI](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/UI/) ## Enumerations - [LicenseFeature](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/enumerations/LicenseFeature) ## Interfaces - [PdfToolsWebSdkOptions](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/interfaces/PdfToolsWebSdkOptions) ## Type Aliases - [LicenseKey](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/type-aliases/LicenseKey) ## Variables - [pdfToolsWebSdk](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/variables/pdfToolsWebSdk) --- ## Interface: PdfToolsWebSdkOptions Options to initialize the Pdftools PDF Web SDK ## Properties ### licenseId? > `optional` **licenseId?**: `number` *** ### licenseKey? > `optional` **licenseKey?**: `` `` `` Pass the license key to activate the product. An empty string may be passed to use a default license which will watermark all pages. #### Default Value `''` *** ### licenseUrl? > `optional` **licenseUrl?**: `string` Url to the License Gateway url *** ### logger? > `optional` **logger?**: `ILogger` Logger class. Must implement ILogger #### Default Value `window.console` *** ### logLevel? > `optional` **logLevel?**: [`LogLevel`](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/web-sdk/@pdftools/namespaces/Core/enumerations/LogLevel) The log level used by the Pdftools PDF Web SDK #### Default Value `LogLevel.ERROR` *** ### path? > `optional` **path?**: `string` Path where all Pdftools PDF Web SDK resources are located. #### Default Value `'./pdftools-web-sdk/'` *** ### producerSuffix? > `optional` **producerSuffix?**: `string` Producer suffix used in the PDF document #### Default Value `Pdftools` --- ## Type Alias: LicenseKey(Type-aliases) > **LicenseKey** = `` `` `` Represents a license key for the Pdftools PDF Web SDK. The license key is a string that contains the license information. --- ## Variable: pdfToolsWebSdk > `const` **pdfToolsWebSdk**: `PdfToolsWebSdk` --- ## April 2025 In April 2025, the Pdftools documentation included the following updates: ## Added - The Pdftools SDK [version 1.9.1](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-191) patch release notes and the Toolbox add-on [version 1.6.1](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-161) patch release notes. - The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.7.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-170-1) release notes. - Conversion Service release notes [version 6.1.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#610). This update also included significant additions and updates for the: - [Simple API Postman collection](https://www.pdf-tools.com/docs/files/conversion-service/conversion_service_simple_api.postman_collection.json) - [Simple API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api/) - Added the Conversion Service [version 5.7.5](https://www.pdf-tools.com/docs/conversion-service/release-notes/#575) LTS patch release notes. - The Conversion Service [Dossier workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/dossier/) page received a major update, including new infographics and many textual improvements. - Major update of the [Automatic update](https://www.pdf-tools.com/docs/conversion-service/update/docker/#automatic-update) section in the Conversion Service documentation. - This documentation now includes the PDF Viewer SDK [version 5.5.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-550) release notes and [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). Also, the following code snippets and their descriptions were added: - [Enable accessibility layer](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer/#enable-accessibility-layer) - [Provide custom HTTP headers when opening a document](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer/#provide-custom-http-headers-when-opening-a-document) ## Changed - Updated descriptions, added images, and improved the style of [PDF Client for Conversion Service](https://www.pdf-tools.com/docs/conversion-service/integrate/gui-client/) page, also the title was changed from PDF Client application (GUI) to **PDF Client for Conversion Service**. ## Fixed - Structural fixes in the [Connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/) page. - Algolia search improvements. --- ## April 2026 In April 2026, the Pdftools documentation included the following updates: ## Added - Added release notes for the Pdftools SDK [version 1.16.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1160) and [version 1.17.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1170), the Toolbox add-on [version 1.12.1](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1121), and the Pdftools SDK Shell Tool [version 1.12.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1120-1). - Added release notes for the PDF Viewer SDK [version 5.15.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5150) and [version 5.15.1](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5151) with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Added a new [OCR](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/) guide category for the Pdftools SDK, including: - An overview of the built-in OCR module with processing dimensions, formats, and use cases. - A step-by-step [OCR a PDF](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-a-pdf/) guide with code samples in C#, Java, Python, and C. - An [OCR best practices](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-best-practices/) page covering performance optimization, thread safety, and resource management. - An [OCR with the Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-with-shell-tool/) guide for the `ocr` command added in version 1.12.0. - Added Java migration guides for moving from [Pdftools SDK 1.14 or earlier to 1.15+](https://www.pdf-tools.com/docs/pdf-tools-sdk/migrate/migrate-to-1-15-java/) and from [Toolbox add-on 1.11 or earlier to 1.12+](https://www.pdf-tools.com/docs/toolbox-add-on/migrate/migrate-to-1-12-java/). - Added a [Customer portal](https://www.pdf-tools.com/docs/licenses/customer-portal/) documentation page with screenshots covering license keys, maintenance dates, page credits, and product builds. - Expanded the Pdftools OCR Service [Getting started](https://www.pdf-tools.com/docs/ocr-service/getting-started/) guides with a license key section, a new [Set up Pdftools OCR Service with Pdftools SDK](https://www.pdf-tools.com/docs/ocr-service/getting-started/windows/set-up-with-sdk/) section with per-language tabs (C#, Java, Python), and interlinks with the Pdftools SDK OCR guides. - Documented all available events emitted by the Conversion Service in the [Conversion workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/conversion/) page. - Added a banner about the deprecation of the legacy My PDF Tools Portal across the documentation. - Updated the Pdftools SDK [OCR best practices](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/ocr/ocr-best-practices/) with additional code snippets. - Improved the Pdftools documentation search with a customized DocSearch, page previews, version deduplication, and better local-result boosting. ## Changed - Renamed **Product kits** to **Product builds** across OCR Service and Conversion Service install and update guides to match the customer portal naming. Updated MSI filenames to a lowercase-hyphen convention (`conversion-service-VERSION.msi`, `ocr-service-VERSION.msi`). - Migrated all code-sample references from the defunct Sample Service download to GitHub: - Redesigned the code-samples pages with the new `SampleRepoCards` component, including per-language icons and a Jupyter/Colab entry that opens notebooks in Google Colab. - Normalized the getting-started intros around a clone-and-navigate workflow. - Added a temporary code-samples-unavailable banner and admonitions to the legacy code-samples pages. - Audited and aligned Pdftools SDK guide code snippets in guides category (archive, assemble, sign, secure, validate). - Updated the Conversion Service [Office conversion](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion/) guide to clarify that Microsoft Office 2024 is the latest supported version, and removed mentions of Office 2019, which is no longer supported. - Removed all references to the legacy My PDF Tools Portal (`my.pdf-tools.com`) and the intermediate "crossroad" pages, after the legacy portal was decommissioned. All flows point directly to `portal.pdf-tools.com`. - Removed the `beta` label from the [PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/) version 5 documentation. - Reordered the Conversion Service workflow items alphabetically in the sidebar (PDF/A entries are sorted 1, 2, 3 instead of 2, 3, 1). - Updated the documentation portal to Docusaurus version 3.10.0 in preparation for Docusaurus version 4, fixing all build errors and warnings. ## Fixed - Dropped physical and directional language ("scroll", "left-hand side", "right-hand side") across the documentation according to general accessibility guidelines. - Fixed an invalid syntax issue in the Conversion Service `openapi.yaml` specification. - Updated dependencies for security and stability, including `marked`, `axios`, `protobufjs`, `posthog-js`, and `docusaurus-plugin-llms`. --- ## August 2025 In August 2025, the Pdftools documentation included the following updates: ## Added - 14 new pages that describe custom profile references for the Pdftools OCR Service. Review [Custom profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/) for more details. - The custom profiles references are split into pages for each [key INI file section](https://www.pdf-tools.com/docs/ocr-service/references/parameters/custom-profiles/#key-ini-file-sections-and-their-purpose). - You can also use [predefined profiles](https://www.pdf-tools.com/docs/ocr-service/references/parameters/#predefinedprofile) instead of custom profiles. - Improved the [Scale the Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/guides/scale/) page with added architectural diagrams. - Conversion Service [version 6.4.1](https://www.pdf-tools.com/docs/conversion-service/release-notes/#641) patch release notes. - The PDF Viewer SDK [version 4.3.5](https://www.pdf-tools.com/docs/pdf-web-viewer/4/release-notes/#435) patch release. ## Changed - The links to prerequisites in the Conversion Service on Windows Server getting started guide now directly download the linked packages in the [version 6](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server/#prerequisites) and [version 5](https://www.pdf-tools.com/docs/conversion-service/5/getting-started/windows-server/#prerequisites) documentation. ## Fixed - The PDF Viewer SDK version 5 getting started guide now correctly mentions the `initialize` method instead of incorrectly mentioning `init` in code snippets. This fix has been made in the [Initialize the viewer](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/#initialize-the-viewer) section. - Minor improvements and typo fixes in the [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) documentation area. - In the legacy products, the [Batch Stamp Tool](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/legacy-products/#batch-stamp-tool) now correctly links to the Toolbox add-on as its replacement. - Fixed Conversion Service LTS [version 4 API](https://www.pdf-tools.com/docs/conversion-service/4/api/conversion-service/) documentation generation issues. - Improvements in the [Offline license configuration](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/#offline-license-configuration) section. - Improved [llms.txt](https://www.pdf-tools.com/docs/llms.txt) and [llms-full.txt](https://www.pdf-tools.com/docs/llms-full.txt). - The documentation website is performing better now due to dependency improvements. --- ## December 2025 In December 2025, the Pdftools documentation included the following updates: ## Added - Implemented extensive restructure and improved navigation: - The [docs landing page](https://www.pdf-tools.com/docs/) now includes the [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/) as a separate documentation area. - Both SDKs now include landing pages with an overview of what each SDK is in a nutshell: [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) and [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/). - The Toolbox add-on now has a dedicated [licensing page](https://www.pdf-tools.com/docs/licenses/products/toolbox-add-on-license/). - The [Other shell tools and SDKs](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/) category now includes labels for 4-Heights, 3-Heights, and Classic, along with an improved landing page. - All sidebars now have better structure and clearly show nesting within the docs. - All sidebars now include a **Docs home** button that leads back to the documentation landing page. - At the top of each page, the breadcrumbs correctly display nesting within the docs. - Additions in the PDF Viewer SDK documentation: - Added a guide [Create custom plugins](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/custom-plugins/). - [Version 5.11.1](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5111) release notes. - [Version 5.12.1](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5121) release notes with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Added release notes for the Conversion Service [version 6.7.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#670), and documentation related to the new [Extraction workflow](https://www.pdf-tools.com/docs/conversion-service/workflows/extraction/). - Release notes for the Toolbox add-on [version 1.11.1](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1111). - Added code examples for the `LicensingService` property in [Use the Licensing Gateway](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#use-the-licensing-gateway). - Added procedure about how to [Find 3-Heights product license](https://www.pdf-tools.com/docs/licenses/products/3-heights-licenses/#find-3-heights-product-license). ## Changed - [PDF Toolbox SDK](https://www.pdf-tools.com/docs/other-shell-tools-and-sdks/pdf-toolbox-sdk/) legacy docs have been moved to the Toolbox add-on docs as versions preceding Toolbox add-on 1.0.0. To switch versions of the docs, click the **Version X.X** button next to the search bar and find **[Legacy 4-H Toolbox version 4.4](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/)**. - All [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/) content was removed from the [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) documentation area as it was moved to its documentation space. ## Fixed - Fixed numerous typos, broken links, misleading tags, and other issues in the Pdftools SDK, Toolbox add-on, Conversion Service, and PDF Viewer SDK documentation. - Fixed incorrect DLL name references (`PdfToolsSdkAPI.dll` to `PdfTools_Toolbox.dll`) in the Toolbox add-on technical notes across all versioned docs. - Fixed incorrect API reference URLs in the Toolbox add-on technical notes, now correctly pointing to `/pdfsdkxt/` endpoints with matching version numbers. - Created hundreds of redirects to the current and versioned docs of the Pdftools SDK. --- ## February 2025 In February 2025, the Pdftools documentation included the following updates: ## Added - All release notes, such as the [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/), [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/), [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/release-notes/), and the PDF Viewer SDK (both [version 5](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/) and [version 4](https://www.pdf-tools.com/docs/pdf-web-viewer/4/release-notes/), received dates for each release. As a result, it is now clear when a release occurred from the release notes. - Added new Python API references for the [Pdftools SDK](https://api-reference.pdf-tools.com/pdfsdk/1.8/pydocs/index.html) and the [Toolbox add-on](https://api-reference.pdf-tools.com/pdfsdkxt/1.5/pydocs/index.html). - This documentation now mentions that the Conversion Service supports Office 2024 (64-bit) for Microsoft Office file conversion. For more information, review [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion/) guide. - The [Update Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/update/windows-server/) and [Update Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/update/docker/) guides received major updates in their structure and delivery. - [Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server/) getting started guide and [Conversion Service in Docker getting started](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/) guide were updated to properly display instructions for the new [Pdftools Portal](https://portal.pdf-tools.com/), including the details about the new trial license key use. Both guides also better explain what applications are installed using the Windows Server and Windows client installers. - PDF Viewer SDK versions [5.2.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-520) and [5.3.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-530) release notes were added to the PDF Viewer SDK release notes. ## Fixed - All [Pdftools SDK getting started guides](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/) received numerous fixes and updates. The initialization step was clearly marked as optional in all these guides. The initialization is necessary for commercial use, but optional for evaluating users. If you need to try the Pdftools SDK, you can do it without the initialization with watermarked results. - Updated commands in the [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) licensing documentation. - Numerous typos were corrected, many broken links were fixed, and many more small updates were made in all areas of this documentation. --- ## February 2026 In February 2026, the Pdftools documentation included the following updates: ## Added - Added release notes for the Conversion Service [version 6.9.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#690) with support for converting S/MIME signed emails (`.p7m`), a progress indicator in the Configurator, and warning subcategories in the Configurator. - Added a getting started guide for deploying [Conversion Service on IONOS Cloud](https://www.pdf-tools.com/docs/conversion-service/getting-started/ionos-cloud/) using Windows virtual machines or Managed Kubernetes. - Added release notes for the PDF Viewer SDK [version 4.3.6](https://www.pdf-tools.com/docs/pdf-web-viewer/4/release-notes/#436). - Added [Microsoft Office is installed but not detected](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#microsoft-office-is-installed-but-not-detected) troubleshooting section for the Conversion Service. - Added supported programming language versions to [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/technical-specifications/#supported-languages-and-frameworks) and [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/technical-specifications/#supported-languages-and-frameworks) technical specifications. - Clarified that PDF Viewer SDK version 5 doesn't require a license key in the [Getting started](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) guide. - Added tags with SEO meta descriptions across all five documentation products (Conversion Service, Pdftools SDK, Toolbox add-on, PDF Viewer SDK, and OCR Service). - Implemented canonical URLs for versioned documentation pages, directing search engines to the latest version. - Added MCP server support to the Kapa.ai widget. As a result, AI tools such as Claude Code and Cursor can access the Pdftools documentation through the Kapa.ai MCP server. To add Pdftools documentation MCP server: 1. Click **Ask AI** widget on the Pdftools documentation portal. 1. Click **Use MCP**, and then select one of the options. ## Changed - Updated the PDF Viewer SDK version 4 documentation to reflect the [npm package scope change](https://www.pdf-tools.com/docs/pdf-web-viewer/4/) in version 4.3.6. ## Fixed - Updated Go code snippets in the Pdftools SDK [Get started with other programming languages](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-other-languages/) guide with idiomatic Go conventions, including short variable declarations and proper cgo import formatting. - Added missing meta descriptions to multiple documentation pages across the Conversion Service, Pdftools SDK, Toolbox add-on, and legacy product documentation. --- ## January 2025 In January 2025, the Pdftools documentation included the following updates: ## Added - The Pdftools SDK documentation was updated after the 1.8.0 SDK release. Documentation for the version 1.5.0 was removed as only three versions of the Pdftools SDK docs are kept on the documentation website for simplicity. For more information, review Pdftools SDK [1.8.0 release notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-180). - The Toolbox add-on received an update to version 1.5.0. Review the [release notes](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-150) for more details. - LTS version of the PDF Viewer SDK received a 4.3.4 patch. Review the [4.3.4 release notes](https://www.pdf-tools.com/docs/pdf-web-viewer/4/release-notes/#434) for the patch information. - Added a new article explaining SSL configuration details for the Licesing Gateway Service (LGS). Review [Configure SSL](https://www.pdf-tools.com/docs/licenses/configure/ssl-licensing-gateway-service) for more details. - The **SSL certificate problem: unable to get local issuer certificate** issue is now documented under licensing [Frequently asked questions](https://www.pdf-tools.com/docs/licenses/#frequently-asked-questions). - The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.6.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-160-1) release notes. ## Changed - Link to our Discord channel was removed. If you need our support, please reach out through the [support page](https://www.pdf-tools.com/docs/support/). ## Fixed - Pdftools SDK [Python getting started](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/) received a major update and fixes. - The [Toolbox add-on getting started guides](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/) also received minor fixes and updates. - [PDF Viewer SDK standard implementation](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/) documentation received an update with fixes to the style, delivery, and code snippet improvements. For more information, review: - [View a PDF](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/view-pdf/) - [Customize the PDF Viewer SDK](https://www.pdf-tools.com/docs/pdf-web-viewer/standard-implementation/customize-viewer/) --- ## January 2026 In January 2026, the Pdftools documentation included the following updates: ## Added - Added release notes for the PDF Viewer SDK [version 5.13.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5130) with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Added release notes for the Conversion Service [version 6.8.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#680). - Added [OpenTelemetry](https://www.pdf-tools.com/docs/conversion-service/monitor/opentelemetry/) documentation for monitoring the Conversion Service. - Added [Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) link to the [documentation landing page](https://www.pdf-tools.com/docs/). - Added [Offline activation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#full-offline-mode-license-activation) and [License key reactivation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#reactivate-license-key) documentation for the Conversion Service. - Added documentation for [Docker Email connectors](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-docker/). - Added link to [Supported LTS product releases](https://www.pdf-tools.com/docs/support/release-management/#supported-lts-product-releases) in the Conversion Service documentation. - Updated the [Pdftools SDK Shell Tool](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk-shell-tool/#features) documentation with new features, including text extraction for LLM ingestion. - Updated the [Getting started](https://www.pdf-tools.com/docs/pdf-web-viewer/getting-started/) guide for the PDF Viewer SDK. - Implemented structured data (JSON-LD schemas) for improved SEO across the documentation website. - Added cookie consent banner to the documentation website. ## Fixed - Fixed a layout shift that sometimes occurred under certain circumstances after images on a page fully loaded. - Fixed broken links and various typos throughout the documentation. - Fixed typos in Conversion Service API documentation. - Fixed the DocSearch widget issue where searched items were not being removed properly. - Fixed broken anchor warnings for code samples pages. - Improved Algolia search with boosted results for important documentation pages. - The What's new documentation area now displays links to all monthly updates in the sidebar. --- ## July 2025 In July 2025, the Pdftools documentation included the following updates: ## Added - Release notes for the Pdftools SDK [version 1.13.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1130), Toolbox add-on [version 1.9.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-190), and the Pdftools SDK Shell Tool [version 1.9.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-190-1). The [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/) documentation pages include updated [API reference](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/) links and [code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples/). - Pdftools SDK documentation now includes the [Accessibility](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/) category with three new guides: - [Create an accessible PDF from scratch](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/create-accessible-pdf/) - [Add logical structure to an existing PDF](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/add-logical-structure-to-existing-pdf/) - [Read PDF logical structure](https://www.pdf-tools.com/docs/toolbox-add-on/guides/accessibility/read-logical-structure/) - Initial [version 1.0.0 of the Pdftools OCR Service](https://www.pdf-tools.com/docs/ocr-service/) documentation with getting started page, configuration pages, release notes, and references. - Conversion Service [version 6.4.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#640) release notes. - Conversion Service documentation now includes an MS Office conversion [Troubleshooting](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/) page, with a [Manual investigation](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#manual-investigation) section. - Patch release notes [5.7.6](https://www.pdf-tools.com/docs/conversion-service/release-notes/#576) for the LTS version of the Conversion Service. - PDF Viewer SDK [version 5.7.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-570) release notes with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Updated section [Offline license activation](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/#offline-license-configuration) in the Licensing Gateway Service (LGS) documentation to provide steps to [Activate license key in the Pdftools Portal](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/#activate-license-key-in-the-pdftools-portal) or [Deactivate license key in the Pdftools Portal](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/#deactivate-license-key-in-the-pdftools-portal). ## Changed - The [Pdftools SDK Python getting started guide](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/) and the [Toolbox add-on Python getting started guide](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-python) now include shorter `pip install` commands. ## Fixed - A script download link works correctly on the [Migration script](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/migration-guide/use-migration-script) page in the legacy PDF Toolbox SDK documentation. - Improved typography of displayed documentation. - Fixed numerous typos, links, and other small improvements in many pages of this documentation. --- ## June 2025 In June 2025, the Pdftools documentation included the following updates: ## Added - The documentation now includes release notes for the Pdftools SDK [version 1.12.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1120), updated API reference links, and code samples. - Pdftools SDK Shell Tool release notes [version 1.8.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-180-1). - The Toolbox add-on received release notes for [version 1.8.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-180) with updated API reference links and code samples. - Pdftools SDK licensing docs now include the [Configure proxy](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) and [Operations](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#operations) sections. - Conversion Service release notes for [version 6.3.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#630) have been added. The following documents received an update: - [Configure stamps and annotations](https://www.pdf-tools.com/docs/conversion-service/configure/configure-stamping/) documentation. - [Stamp and annotation](https://www.pdf-tools.com/docs/conversion-service/workflows/stamping/) workflow documentation. - Minor updates in the [Cryptographic providers](https://www.pdf-tools.com/docs/conversion-service/configure/configure-signature/set-up-signature/). - Added two new troubleshooting sections in the Conversion Service Microsoft Office conversion documentation: - [The server process could not be started because the configured identity is incorrect (COM exception 0x8000401a)](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#the-server-process-could-not-be-started-because-the-configured-identity-is-incorrect-com-exception-0x8000401a). - [Access is denied (COM exception 0x80070005)](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#access-is-denied-com-exception-0x80070005) - Conversion Service OCR documentation now includes online ABBYY license type information in the [Activate ABBYY license](https://www.pdf-tools.com/docs/conversion-service/configure/ocr/configure-ocr-your-own-license-key/#activate-abbyy-license) section and related sub-sections. - Licensing documentation now mentions that you can configure Conversion Service to be used in the [containerized mode](https://www.pdf-tools.com/docs/licenses/configure/docker-licensing-gateway-service/) and links you to the Conversion Service [Configure containers using Docker Compose](https://www.pdf-tools.com/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose) documentation section, where you can find an example of Docker Compose YAML file that enables LGS containerized mode configuration. - The Conversion Service [Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server/) and [Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/) getting started guides now include an improved description explaining that you need to use fonts installed on your processing machine. - PDF Viewer SDK documentation received version [5.6.0 release notes](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-560) and updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Legacy Toolbox SDK received patches [version 4.4.10](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/release-notes#version-4410) and [version 4.4.11](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/release-notes#version-4411). - Enabled search through tags within documentation product areas. Tags will directly lead you to the referenced page. You can find the tags at the end of each page and list all tags within a product area. Tags are separate for each documentation area. The following list includes three main documentation product areas where the tags were added: - [Pdftools SDK tags](https://www.pdf-tools.com/docs/pdf-tools-sdk/tags/) - [Conversion Service tags](https://www.pdf-tools.com/docs/conversion-service/tags/) - [PDF Viewer SDK tags](https://www.pdf-tools.com/docs/pdf-web-viewer/tags/) - Example: Try clicking on a tag like [Merge and split PDFs](https://www.pdf-tools.com/docs/pdf-tools-sdk/tags/merge-and-split-pd-fs/) at the end of a page to jump directly to related documents. - [LLMs.txt](https://www.pdf-tools.com/docs/llms.txt) and [LLMs-full.txt](https://www.pdf-tools.com/docs/llms-full.txt) were added to provide LLMs with an easily parsable text format. ## Changed - In the Conversion Service documentation: - [Conversion Service licensing](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/) documentation now mentions **page credits** instead of **credits**. This change can better explain the usage-based license key functionality (instead of **X credits per page**, we now state **X page credits**). - The **Stamping** workflow was renamed to [Stamp and annotation](https://www.pdf-tools.com/docs/conversion-service/workflows/stamping/). - The **Warnings** configuration section was renamed to **Events**. - The **Document Optimization** processing step (included in all PDF/A workflows) was renamed to **Compression and Optimization**. - The **What's new** tag was removed from the What's new documentation area. ## Fixed - Links to the [Pdftools Portal](https://portal.pdf-tools.com/) have been updated. - All pages in the Conversion Service [Workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/) documentation category received correct level headers, typo fixes, screenshot size adjustments, and other updates. --- ## March 2025 In March 2025, the Pdftools documentation included the following updates: ## Added - Pdftools SDK documentation now includes the [Embed e-invoice guide](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/e-invoice/) and a related code sample, Create a ZUGFeRD invoice ([C](https://github.com/pdf-tools/sdk-examples-c/tree/main/Zugferd), [C#](https://github.com/pdf-tools/sdk-examples-csharp/tree/main/Zugferd), [Java](https://github.com/pdf-tools/sdk-examples-java/tree/main/Zugferd), [Python](https://github.com/pdf-tools/sdk-examples-python/tree/main/Zugferd)). You can use the provided information and code sample to create e-invoices in both ZUGFeRD and Factur-X formats. - Added Pdftools SDK [version 1.9.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-190) release notes and Toolbox add-on [version 1.6.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-160) release notes. - Conversion Service release notes for [version 6.0.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#600) were added. Two significant documentation updates are connected to this version: - Conversion Service documentation now includes the [Conversion Service on OpenShift](https://www.pdf-tools.com/docs/conversion-service/configure/configure-openshift/) guide. - The beta version of the Configurator Web was released with an initial minimal documentation section, [Configure profiles using Configurator Web](https://www.pdf-tools.com/docs/conversion-service/configure/configure-profiles-docker/#configure-profiles-using-configurator-web). - The Conversion Service log files are now explained in the [Conversion Service on Windows Server](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server/) getting started guide. - PDF Viewer SDK [version 5.4.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-540) release notes. The PDF Viewer SDK [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/) were also updated. - Added [PDF Toolbox SDK 4.4.9](https://www.pdf-tools.com/docs/toolbox-add-on/legacy-4.4/release-notes#version-449) patch release notes. Note that PDF Toolbox SDK features and functionality are now included in the Toolbox add-on for Pdftools SDK. - The Algolia Search widget in this documentation now includes an option to use your search input in the kapa.ai widget. When you search for a term in the Algolia Search widget, you can click **Can you tell me about**, which is marked as the first search result, to get an answer from kapa.ai, an LLM trained specifically on the data from this documentation website. - The documentation website now includes lightboxes for images. When you click an image, it is enlarged to display more detail. The lightbox can be closed by pressing any key on your keyboard or scrolling. ## Changed - The **Download** button included in the code samples was moved below the programming language selection to clarify that these code samples, such as [Pdftools SDK code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) or [Toolbox add-on code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples), must be downloaded so you can use them. - The optional [Install and configure additional clients](https://www.pdf-tools.com/docs/conversion-service/getting-started/windows-server/#optional-install-and-configure-additional-clients) section in the Conversion Service getting started guide was moved within the guide. - If you are installing the Conversion Service on regular Windows (instead of Windows Server), you no longer need the `msiexec /i ConversionService-VERSION_NUMBER.msi PDF_TOOLS_DISABLE_OS_CHECK=1` command to enable the installation. This step was removed from the [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/) getting started guide. - The PDF Toolbox SDK version 3.11 and the Conversion Service version 3.11 were removed from the [Supported LTS product releases](https://www.pdf-tools.com/docs/support/release-management/#supported-lts-product-releases) table in [Release management](https://www.pdf-tools.com/docs/support/release-management/) documentation. The official LTS support for both product versions ended in 2024. PDF Viewer SDK version 4.3 was added as one of the LTS versions. ## Fixed - Fixed documentation website caching issues and related broken links. - Simplified headers, labels, and clarified placeholders in [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) documentation. - Removed repeated word **Configure** in nearly every Conversion Service [Configure](https://www.pdf-tools.com/docs/conversion-service/configure/) documentation section item. - Added a note that the Licensing Gateway Service is already installed with the Conversion Service on Windows Server. Installing LGS a second time may render the Conversion Service unusable. The note also clarifies that full offline mode functionality is unavailable in the Conversion Service. Review [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) for more information. --- ## March 2026 In March 2026, the Pdftools documentation included the following updates: ## Added - Added release notes for the Pdftools SDK [version 1.15.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1150), the Toolbox add-on [version 1.12.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1120), and the Pdftools SDK Shell Tool [version 1.11.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1110-1). - Published release notes for the Conversion Service [version 6.10.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#6100). - Added release notes for the Pdftools OCR Service [version 1.1.0](https://www.pdf-tools.com/docs/ocr-service/release-notes/#version-110) and [version 1.1.1](https://www.pdf-tools.com/docs/ocr-service/release-notes/#version-111). - Added release notes for PDF Viewer SDK [version 5.14.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5140) with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Added forward proxy configuration for the Licensing Gateway Service (LGS) in the following pages: - In the **connected mode** documentation as [Configure a forward proxy](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/#configure-a-forward-proxy) section. - In the **containerized mode** documentation as [Configure a forward proxy](https://www.pdf-tools.com/docs/licenses/configure/docker-licensing-gateway-service/#configure-a-forward-proxy) section. - Added section for LGS [Full offline mode in Docker](https://www.pdf-tools.com/docs/licenses/configure/docker-licensing-gateway-service/#full-offline-mode-in-docker). - Added section [Activate one license key on multiple machines](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/#activate-one-license-key-on-multiple-machines) in the offline LGS documentation. - Added downloadable OpenAPI specification files to the Conversion Service [API references](https://www.pdf-tools.com/docs/conversion-service/api/#openapi-specifications) page. The Conversion Service OpenAPI specification files were improved for better compliance with the OpenAPI 3.1 standard. - Updated Java getting started guides for the [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java/) and the [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/getting-started/toolbox-java/) with separate Maven and Gradle build tool instructions. - Updated the PDF Viewer SDK [Create custom plugins](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/custom-plugins/) guide with corrected sample code. ## Changed - Restructured the Conversion Service [Simple API reference](https://www.pdf-tools.com/docs/conversion-service/api/simple-api/simple-api/) documentation. Collapsed per-profile endpoint pages into two parameterized endpoint routes with individual pre-installed connection profile pages. - Migrated client-side redirects to server-side 301 redirects for improved SEO performance. ## Fixed - Corrected the Licensing Gateway Application (LGA) command-line help reference in the [offline licensing](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) documentation. - Added security metadata to the Conversion Service Advanced API OpenAPI specification. - Applied style enforcements and fixes across the Pdftools SDK and Toolbox add-on documentation. --- ## May 2025 In May 2025, the Pdftools documentation included the following updates: ## Added - Pdftools SDK code samples now include links to Jupyter notebooks labeled as **Open in Colab** buttons. Review the following code samples: - [Pdftools SDK code samples](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) - [Toolbox add-on code samples](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) - Release notes for the Pdftools SDK versions [1.10.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1100), [1.11.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1110), and patch [1.11.1](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1111) have been added to the documentation with updated API reference links and code samples. - The Toolbox add-on received release notes for [version 1.7.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-170) and patch [version 1.7.1](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-171). - The Conversion Service documentation now includes release notes for [version 6.2.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#620). This version came with the following documentation updates: - The [Licensing Gateway Service (LGS) full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) is now enabled for the Conversion Service. - The Accessibility workflow initial documentation has been published. Note: The Accessibility workflow was removed in Conversion Service version 6.10.0. - The [Licensing credit count](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#licensing-credit-count) and [Calculating credits](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#calculating-credits) sections have been added to the Pdftools SDK licensing documentation. - The **What's new** documentation category you are reading now has been created to inform you about updates in the Pdftools documentation. The entries in this category have been added retrospectively since the beginning of the year 2025. ## Changed - The `latest` tag was removed from the Conversion Service Docker documentation. For more information, review [version 6.2.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#620) release notes. - The customer portal URL was updated from `https://www.pdf-tools.com/en/mypdftools/licenses-kits/` and `https://my.pdf-tools.com/en/mypdftools/licenses-kits/` to the [Pdftools Portal](https://portal.pdf-tools.com/). ## Fixed - The [Convert Microsoft Office files](https://www.pdf-tools.com/docs/conversion-service/configure/office-conversion/) page in the Conversion Service documentation has been updated. You can now directly link to all subsections previously hidden within tabs. Additionally, wording, formatting, and various minor issues have been addressed. - Minor fixes have been applied to the [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) documentation landing page, [Conversion Service in Docker](https://www.pdf-tools.com/docs/conversion-service/getting-started/docker/) guide, PDF Viewer SDK [Custom implementation guides](https://www.pdf-tools.com/docs/pdf-web-viewer/guides/), and the [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) licensing documentation. - General deployment processes for documentation have been enhanced to ensure greater stability and accessibility. --- ## November 2025 In November 2025, the Pdftools documentation included the following updates: ## Added - Added Pdftools OCR Service release notes for [version 1.0.2](https://www.pdf-tools.com/docs/ocr-service/release-notes/#version-102). - Added [Server execution failed (COM exception 0x80080005)](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#server-execution-failed-com-exception-0x80080005) in the Conversion Service Office troubleshooting documentation. - Added Conversion Service patch release notes for [version 6.6.1](https://www.pdf-tools.com/docs/conversion-service/release-notes/#661). - Updated section [Remaining page credit count](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#remaining-page-credit-count) and added section [View page credits consumption in the Conversion Service Configurator](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#view-page-credits-consumption-in-the-conversion-service-configurator). - Added release notes for the PDF Viewer SDK [version 5.11.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5110) with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Updated supported Windows Server versions and names of configuration files in [Installation and configuration](https://www.pdf-tools.com/docs/conversion-service/migrate/installation/) of the Migrate from the 3-Heights® Document Converter documentation category. - Added a row and column table highlighting on this documentation website. ## Fixed - The [Find the license key](https://www.pdf-tools.com/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key) section now includes a correct procedure linking to the new Pdftools Portal. - Style improvements in the Conversion Service [Office troubleshooting](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/) guide. - Updated [Connected mode](https://www.pdf-tools.com/docs/licenses/configure/licensing-gateway-service/) licensing page to clarify that you can use the same license key on multiple machines simultaneously in connected mode. - Updated dependencies, font scaling CSS fixes, and style improvements for better readability and performance of this documentation website. --- ## October 2025 In October 2025, the Pdftools documentation included the following updates: ## Added - Added the Pdftools SDK documentation release notes for [version 1.14.0](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1140) and updated links to [API references](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/). - Added section [Add custom font lookup paths](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/general-notes/#add-custom-font-lookup-paths) to the Pdftools SDK technical notes. - Improved and optimized performance of the [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) and the [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) code sample pages. - Added the Toolbox add-on documentation release notes for [version 1.11.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1110) and updated links to [API references](https://www.pdf-tools.com/docs/toolbox-add-on/api-references/). - Added release notes for the Pdftools SDK Shell Tool [version 1.10.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1100). - Added release notes for the Conversion Service [version 6.6.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#660). This Conversion Service release also includes documentation related to newly added Gmail connectors with the following sections and subsections: - [Watched Mailbox (Gmail)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-gmail) - [Watched Mailbox (Gmail App Passwords)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-gmail-app-passwords) - [Watched Mailbox (Gmail OAuth 2.0)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#watched-mailbox-gmail-oauth-20) - [Output Mailbox (Gmail)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-gmail) - [Output Mailbox (Gmail App Passwords)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-gmail-app-passwords) - [Output Mailbox (Gmail OAuth 2.0)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#output-mailbox-gmail-oauth-20) - [Send Email (Gmail)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-gmail) - [Send Email (Gmail App Passwords)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-gmail-app-passwords) - [Send Email (Gmail OAuth 2.0)](https://www.pdf-tools.com/docs/conversion-service/integrate/connectors/email-connectors/email-connectors-windows#send-email-gmail-oauth-20) - PDF Viewer SDK release notes and updated API references for versions: - [5.10.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-5100) - [5.9.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-590) - Expanded [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/) documentation with more information about offline license key usage, and a precise procedure and prerequisites. - This documentation website now offers an enhanced sidebar contrast and improved visibility for currently open pages. ## Fixed - Updated [PDF Viewer SDK architecture](https://www.pdf-tools.com/docs/pdf-web-viewer/api-references/) documentation. - Removed tabs with nested sub-headings from the Pdftools SDK [General technical notes](https://www.pdf-tools.com/docs/pdf-tools-sdk/api-references/technical-notes/general-notes/) for better clarity. - Expanded [Excel conversion fails with a “Generic” error (COM exception 0x800a03ec)](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/#excel-conversion-fails-with-a-generic-error-com-exception-0x800a03ec) section in the [Troubleshooting Microsoft Office file conversion documentation](https://www.pdf-tools.com/docs/conversion-service/configure/office-troubleshooting/). - When you switch pages on this documentation website, the displayed fonts no longer switch between fonts for a split second. - Fixed numerous typos and other minor issues in many documentation pages. --- ## September 2025 In September 2025, the Pdftools documentation included the following updates: ## Added - Restructured and expanded the Pdftools OCR Service documentation: - Consolidated [Get started with OCR in the Conversion Service](https://www.pdf-tools.com/docs/ocr-service/getting-started/) guide to provide information from installation to initial configuration. - New page [Pdftools OCR Service licensing](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/) with [Configuration in connected mode and full offline mode](https://www.pdf-tools.com/docs/licenses/products/ocr-service-license/#configuration-in-connected-mode-and-full-offline-mode) section. The page includes details on how to configure the Pdftools OCR Service in both Connected mode and Full offline mode. Additionally, the Pdftools OCR Service licensing includes additional setup steps that you must follow for the OCR service after configuring the [Pdftools Licensing Service](https://www.pdf-tools.com/docs/licenses/configure/) in Full Offline mode or Connected mode. - New page [Work with profiles](https://www.pdf-tools.com/docs/ocr-service/guides/profiles/). - Improved directory structure and information architecture, more comprehensive URLs, shortened titles and sidebar labels, and fixes in [References](https://www.pdf-tools.com/docs/ocr-service/references/). - Added release notes for [Version 1.0.1](https://www.pdf-tools.com/docs/ocr-service/release-notes/#version-101). - The Pdftools SDK released a patch version [1.13.1](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-1131). - The Toolbox add-on SDK released a minor version [1.10.0](https://www.pdf-tools.com/docs/toolbox-add-on/release-notes/#version-1100). - The Pdftools SDK Shell Tool released a patch version [1.9.1](https://www.pdf-tools.com/docs/pdf-tools-sdk/release-notes/#version-191-1). - The Conversion Service released the following versions: - Minor version [6.5.0](https://www.pdf-tools.com/docs/conversion-service/release-notes/#650). - Patch version [6.4.2](https://www.pdf-tools.com/docs/conversion-service/release-notes/#642). - The Conversion Service licensing includes the following new sections: - [Full offline mode license activation](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#full-offline-mode-license-activation) - [Reactivate license key](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#reactivate-license-key) - [Remove license key](https://www.pdf-tools.com/docs/licenses/products/conversion-service-license/#remove-license-key) - The PDF Viewer SDK released minor version [5.8.0](https://www.pdf-tools.com/docs/pdf-web-viewer/release-notes/#version-580) with updated [API references](https://www.pdf-tools.com/docs/pdf-web-viewer/category/api-references/). - Added section [LGS supported operating systems and environments](https://www.pdf-tools.com/docs/licenses/configure/#lgs-supported-operating-systems-and-environments). - [Full offline mode](https://www.pdf-tools.com/docs/licenses/configure/offline-licensing-gateway-service/) page includes a note about the limitations of full offline mode, and the tabs that display Linux Snap package installation mention that the Licensing Gateway Service requires **glibc 2.34+**. - The [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/code-samples) and [Toolbox add-on](https://www.pdf-tools.com/docs/toolbox-add-on/code-samples) **code samples** received the following updates: - Added the right panel table of contents (TOC) to provide an overview of categories within the samples. - Fixed code highlighting inconsistency, dark and light mode switching. - The code samples now use the correct code theme in both light and dark modes. - Responsive TOC for smaller screens added on top of the pages as a clickable **On this page** modal. ## Changed - Removed references to [languages](https://www.pdf-tools.com/docs/ocr-service/references/ocr-languages/) that the Pdftools OCR Service doesn't support. These languages include Arabic, Burmese, Chinese (Simplified and Traditional), Farsi, Hebrew, Japanese, Korean, Latvian (written in Gothic script), Old English, Old French, Old German, Old Italian, Old Slavonic, Old Spanish, Pashto, Thai, Urdu, Vietnamese, and Yiddish. To request support for any of these languages, let us know using the [contact page](https://www.pdf-tools.com/contact/). ## Fixed - Typo fixes, delivery, and style improvements in all pages within the [Workflows](https://www.pdf-tools.com/docs/conversion-service/workflows/) category of the Conversion Service docs. - Updated the Algolia Search integration to the latest version and reimplemented its custom features. To open the search modal, use `Ctrl` + `k` on Linux or Windows, and `⌘`+ `k` on macOS. Example custom search feature: When you search within a product area, such as [Pdftools SDK](https://www.pdf-tools.com/docs/pdf-tools-sdk/), [Conversion Service](https://www.pdf-tools.com/docs/conversion-service/), or [What's new](https://www.pdf-tools.com/docs/whats-new/), the search displays results from that product area first. - Updated code sample downloadable links in the [Guides](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/) category with links to newly added languages for each use case, making them more prominently visible. For example, the [Archive a PDF document to PDF/A](https://www.pdf-tools.com/docs/pdf-tools-sdk/guides/archive/archive-pdf-pdfa) guide includes a visible admonition stating **Quick start with a code sample** with bold links to each sample, including C, Python, and Visual Basic. - Fixed the Conversion Service version selection menu from appearing on the What's new page. - The [llms.txt](https://www.pdf-tools.com/docs/llms.txt) and [llms-full.txt](https://www.pdf-tools.com/docs/llms-full.txt) autogeneration issues.