# 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 llmtxt.org standard.

## Conversion Service

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The Conversion Service is a comprehensive on-premises solution for automating your document processes. It takes input documents of different formats from various 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 a powerful REST APIs (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](configure/how-cs-works.mdx).
:::

## Key features

- **High throughput** job processing
- Specialized **workflows**: Archive PDF/A-2, Archive PDF/A-3, Archive PDF/A-1, Conversion, Invoice, Dossier
- Multiple **configuration profiles** for each workflow
- Convenient **conversion 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** or **Simple** APIs.

## Compatible operating systems

The Conversion Service is available for the following operating systems:

| Version             | Bit version |
| ------------------- | ----------- |
| Windows Server 2019 | x64         |
| Windows Server 2022 | x64         |
| Windows Server 2025 | x64         |

| 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
- To convert Microsoft Word, Excel, and PowerPoint files to PDFs with the Conversion Service, you need a valid Microsoft 365 for Business license.
- For Microsoft Office file conversion, we recommend using the English (en-US) version of the operating system. For more information, review [Microsoft Office conversion](configure/office-conversion.mdx).
:::

## 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 drive to boost the performance, as the Conversion Service heavily relies on input/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 is beyond the scope of Pdftools support. If the service works with the firewall disabled or on a local machine, any issues arising due to firewall configuration are your responsibility.

| Rule | Port |
| --------- | ---- |
| Inbound | 13033 (HTTP/HTTPS) |
| Inbound | 13034 (HTTP/HTTPS) |
| Inbound | 9999 (HTTP) |
| Outbound | Integration related ports (for example, REST Output, Mailbox-related Connectors) |

### Data encryption standards

It is recommended to ensure limited access to the machine, as the files that are stored on the system are not 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)
- 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)
- 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. 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.

### Advanced API

The examples of Advance API use cases include the following:

- Merge hundreds of documents into a single PDF using the Dossier 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).

---

## Conversion Service API references

import DocCardList from '@theme/DocCardList';

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](../getting-started/api/README.mdx)** guide.
:::

:::note Postman collection
You can also use the available Postman collections:
- [Simple API Postman collection](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json)
- [Advanced API Postman collection](pathname:///files/conversion-service/conversion_service_advanced_api.postman_collection.json)
:::

---

## Add data to job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

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.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}},"409":{"description":"The job has already been started or canceled.","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["message","title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["message","title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"}}}},"415":{"description":"- The content type is not multipart/form-data, application/json or application/xml\n- The content type of the options field in the multipart/form-data content is not application/json\n"}}}
>

---

## Advanced API

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

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 also lets you convert files of any size (larger than 100 MB).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

```

---

## Cancel job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

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`.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}}}}
>

---

## Create new job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

Create a new job for processing using the provided `workflow` and `profile`.
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 `creteJob` API request.
- **Document options**: Set in the `addData` API request.

---

## Delete job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

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.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}}}}
>

---

## Get job info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

Get job info.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}}}}
>

---

## Get job result data

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

Get result data, typically a document, of a job that has completed successfully.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}},"409":{"description":"Unable to get result data, e.g. because it is not yet available. Call `getJobResult` first."}}}
>

---

## Get job result

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

This request returns 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.
Therefore, it is recommended to handle request timeouts, especially for long-running jobs or for services under high load.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}},"409":{"description":"The job has no result, e.g. because it has not yet been started."}}}
>

---

## Get the service status

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

Get the service status.

---

## List all jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

List all jobs and their statuses.

---

## List available workflows

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

List available workflows.

---

## Start job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

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.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}},"409":{"description":"The job has already been started or canceled.","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["message","title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["message","title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"}}}}}}
>

---

## Store job result data

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

Store the result data by sending it to a web server via HTTP(S) request.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/jobNotFound\n  Job not found.\n  The job with ID 'job_XYZ' could not be found\n  404\n\n"}}}}},"409":{"description":"Unable to get result data, e.g. because it is not yet available. Call `getJobResult` first."}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The All to PDF Profile converts any supported input document into a standard PDF. REST input JSON allows for structured input and output for your documents to be converted to PDF. Upload documents using a URL or in Base64 encoded format.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The All to PDF Profile converts any supported input document into a standard PDF. The REST input plain HTTP endpoint supports the conversion of various document formats to PDF. In the request body, provide a file you want to convert as the `multipart/form-data` content type.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Merge Profile merges multiple documents into a single PDF dossier. REST input JSON allows for structured input and output for your documents to be merged into a single PDF. Upload documents using a URL or in Base64 encoded format.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Merge Profile merges multiple documents into a single PDF dossier. The REST input plain HTTP endpoint supports merging multiple documents into a single PDF. In the request body, provide files you want to merge as the `multipart/form-data` content type.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Archive PDF/A-2 endpoint outputs PDFs in the PDF/A-2 archival standard (this is a recommended archival format). The REST input JSON allows for structured input and output for your documents. Upload documents using a URL or in Base64 encoded format.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Archive PDF/A-2 endpoint outputs PDFs in the PDF/A-2 archival standard (this is a recommended archival format). The REST input plain HTTP endpoint supports the conversion of large files (larger than 100 MB). In the request body, provide a file you want to convert as the `multipart/form-data` content type.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Archive PDF/A-3 endpoint outputs PDF documents compliant with the PDF/A-3 archival standard, recommended especially for use cases such as electronic invoicing (e-invoices). REST input JSON allows for structured input and output for your documents. Upload documents using a URL or in Base64 encoded format.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Archive PDF/A-3 endpoint outputs PDF documents compliant with the PDF/A-3 archival standard, recommended especially for use cases such as electronic invoicing (e-invoices). The REST input plain HTTP endpoint supports the conversion of large files (larger than 100 MB). In the request body, provide a file you want to convert as the `multipart/form-data` content type.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready for Email PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, specifically with ready for email optimization. The REST input JSON endpoint supports structured input and output for documents intended as email attachments. Documents can be uploaded either using a URL or as a Base64-encoded string.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready for Email PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, specifically with ready for email optimization. The REST input plain HTTP endpoint supports the conversion of large files (larger than 100 MB) intended for email attachments. To use this endpoint, submit the file you wish to convert as `multipart/form-data` in the HTTP request body.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready for Web PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, optimized specifically for web viewing. The REST input JSON endpoint supports structured input and output for documents intended for online presentation. Documents can be uploaded either using a URL or as a Base64-encoded string.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready for Web PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, optimized specifically for web viewing. The REST input plain HTTP endpoint supports the conversion of large files (larger than 100 MB). To use this endpoint, submit the file you wish to convert as `multipart/form-data` in the HTTP request body.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready to Print PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, optimized specifically for printing. The REST input JSON endpoint enables structured input and output. You can upload documents either using a URL or as a Base64-encoded string.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Ready to Print PDF/A-2 workflow outputs PDF documents compliant with the PDF/A-2 archival standard, optimized specifically for printing. The REST input plain HTTP endpoint supports the conversion of large files (larger than 100 MB). To use this endpoint, submit the file you want to convert as `multipart/form-data` in the HTTP request body.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input JSON

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Repair Profile validates and repairs PDFs. The REST input JSON allows for structured input and output for PDF documents to be validated and repaired. To use this endpoint, upload documents using a URL or in Base64 encoded format.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## REST input plain HTTP

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

  

The Repair Profile validates and repairs PDFs. The REST input plain HTTP endpoint supports validating and repairing large PDF files (larger than 100 MB). To use this endpoint, provide files you want to repair as the `multipart/form-data` content type in the request body.

  

  

\n  http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat\n  Unsupported file format.\n  A file format is not supported.\n  415\n\n"}}}}},"422":{"description":"Unprocessable file. Returns `ProblemDetails`:\n- The conformance is not compatible.\n- The file is corrupt.\n- A generic error happened during processing.\n- One of the specified options is invalid.\n- The password is missing or incorrect.\n- A file contains a feature that is not supported.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Incompatible conformance","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/conformance","title":"Incompatible conformance.","detail":"The conformance is not compatible.","status":422}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Incompatible conformance","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/conformance\n  Incompatible conformance.\n  The conformance is not compatible\n  422\n\n"}}}}},"500":{"description":"An Internal server error. Returns `ProblemDetails`:\n- The job was canceled.\n- The service is not configured correctly.\n- An internal error happened during processing.\n- A timeout occurred during processing.\n- If an unknown error occurs the message you receive is empty.\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorJson:":{"summary":"Server error","value":{"type":"http://www.pdf-tools.com/service/rest/errors/workflow/internal","title":"Internal server error.","detail":"An internal error happened during processing.","status":500}}}},"application/problem+xml":{"schema":{"type":"object","description":"Problem details (RFC 7807).","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. Note that this URI cannot be dereferenced."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["title","detail","status"],"xml":{"name":"problem","namespace":"urn:ietf:rfc:7807"},"title":"problemDetails"},"examples":{"serverErrorXml":{"summary":"Server error","value":"\n  http://www.pdf-tools.com/service/rest/errors/workflow/internal\n  Internal server error.\n  An internal error happened during processing\n  500\n\n"}}}}}}}
>

---

## Simple API

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

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.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

```

---

## 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](configure-win-service.mdx)**: a program added to the Windows Start menu during installation lets you determine the service's configuration using an easy interface.
- **[Environmental values](configure-docker-container.mdx)**: 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](../workflows/README.mdx). To change the options associated with a profile, you need to [configure profiles](configure-profiles.mdx).

## Configuring Office conversion
If you plan to convert Microsoft Office files, [configure your Microsoft Office installation](office-conversion.mdx).
To convert Microsoft Word files that include tracked changes (revisions, also called redlining), review [Configure conversion of redlined Microsoft Word documents](./word-track-changes.mdx).

:::caution
To convert Microsoft Office files, a valid license is required.
:::

---

## Configure connections

import useBaseUrl from '@docusaurus/useBaseUrl';

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](../../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](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#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](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-plain-http)| Convert files sent in the request body in HTTP format, either as a single file or multiple files. |
|  | [Watched Folder](../integrate/connectors/folder-connectors.mdx#watched-folder)| Convert all files placed into a configurable input directory. |
|  | [Watched Mailbox (Exchange Online)](../integrate/connectors/email-connectors.mdx#watched-mailbox-exchange-online) | Convert all emails that are placed into a configurable Microsoft Exchange Online mailbox. |
|  | [Watched Mailbox (IMAP)](../integrate/connectors/email-connectors.mdx#watched-mailbox-imap)| Convert all emails that are placed into a configurable IMAP mailbox. |
| **Output** | [Create Text file](../integrate/connectors/folder-connectors.mdx#create-text-file) | Create a text file with additional information. |
|  | [Execute Command](../integrate/connectors/other-connectors.mdx#execute-command) | Execute a configurable command with arguments on the files. |
|  | [Output Folder](../integrate/connectors/folder-connectors.mdx#output-folder) | Copy files into a configurable output directory. |
|  | [Output Mailbox (Exchange Online)](../integrate/connectors/email-connectors.mdx#output-mailbox-exchange-online) | Copy files to a configurable mailbox on a Microsoft Exchange Online server. |
|  | [Output Mailbox (IMAP)](../integrate/connectors/email-connectors.mdx#output-mailbox-imap) | Copy files to a configurable mailbox on an IMAP server. |
|  | [REST Output](../integrate/connectors/rest-connectors/rest-output-connectors.mdx#rest-output) | Post files as a multipart/form-data request to a configurable output URL. |
|  | [Send Email (Exchange Online)](../integrate/connectors/email-connectors.mdx#send-email-exchange-online) | Send an email to a configurable recipient using a Microsoft Exchange Online server.
|  | [Send Email (SMTP)](../integrate/connectors/email-connectors.mdx#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**.

---

## 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:
            # Dependant 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:
            # Dependant on configuration-updater. The service starts only after the update was completed successfully.
            configuration-updater:
                condition: service_completed_successfully
            # Dependant on license-gateway. The service starts only after license-gateway healthcheck pass.
            license-gateway:
                condition: service_healthy
    
    configuration-updater:
        # Configuraiton 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-based 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](../integrate/connectors/folder-connectors.mdx#watched-folder)
- REST input connectors:
    - [REST input plain HTTP](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-plain-http)
    - [REST input JSON](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#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](../integrate/rest-api.mdx) as: `http[s]://‹hostname›:‹port›/conversion/v1.0/rest`.

This is the endpoint URL used by clients such as the [shell client](../integrate/shell-client.mdx). 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

If you want to convert Word, Excel, and PowerPoint documents to PDF, you need to set up the Office configuration. See [Convert Office Documents](office-conversion.mdx)

:::

---

## Configure emails

import InfoCirlce from '/img/info-circle.svg'

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 scroll down to the **Email Settings** section. 

![Email Setting section in the profile configuration](/img/config_email_section.png)

For Archive 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.

![Document Settings section in the profile configuration](/img/config_document-settings.png)

- **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.

![Conversion Service configurator built-in documentation](/img/config_document-settings-built-in-help.png)
:::

---

## 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 are specific to each workflow. Options are available for the [Conversion](../workflows/conversion.mdx), [Invoice](../workflows/invoice.mdx), [Dossier](../workflows/dossier.mdx), [PDF/A-2](../workflows/pdfa_2.mdx), [PDF/A-3](../workflows/pdfa_3.mdx), and [PDF/A-1](../workflows/pdfa_1.mdx) workflows.

The default values taken for a profile are determined in the [profile settings](configure-profiles.mdx). 
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](../workflows/metadata.mdx)). 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.

![User Option Configuration](/img/config_custom_option_name.png)

You can use the custom name to pass a specific value when you perform a workflow using that profile.

---

## Configure OCR

import InfoCirlce from '/img/info-circle.svg'

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.

:::info
The Conversion Service supports ABBYY FineReader Engine v11 and v12.
:::

## 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 Pdftools [Customer portal](https://my.pdf-tools.com/en/mypdftools/licenses-kits/).
:::

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.

    ![The **OCR Settings** processing toggle enabled.](/img/config_enable_ocr.png)

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.

![Conversion Service configurator built-in documentation](/img/config_ocr_built-in-help.png)
:::

### 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.

  ![Configure the ABBYY FineReader OCR Engine with the Conversion Service Configurator](/img/config_profile_ocr_engine_abbyy.png)

:::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
See 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.

#### Languages
Configure all languages that appear in your documents to improve recognition accuracy.

:::tip Configure all languages included in the documents
The ABBYY FineReader Engine only recognizes characters that are used in these languages.
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.

## Using the 3-Heights® OCR Service
A direct configuration of the ABBYY FineReader Engine (v11 or v12) is recommended.
It is also possible to configure OCR through the 3-Heights® OCR Service, but it is not recommended. Use the 3-Heights® OCR Service only if your Conversion Service and a Document Converter installation use an ABBYY license simultaneously.
For more information about the configuration of the 3-Heights® OCR Service, see [Migrating from 3-Heights® Document Converter](../migrate/ocr.mdx) documentation.

---

## 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](../api/advanced-api/advanced-api.info.mdx)), 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](../getting-started/windows-server.mdx#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](./office-conversion.mdx#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](../getting-started/docker.mdx#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](./configure-docker-container.mdx#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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Plugins are non-standard components used for extending the Conversion Service with custom workflows. 

## Manage plugins

Depending on your installation, plugins are managed differently.

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.
:::

![Plugins tab of the Conversion Service Configurator](/img/config_plugins.png)

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 of `Install \Path{Plugin-x.y.0.zip` dockerfile for Conversion Service version 4.0.0**

```
  FROM pdftoolsag/conversion-service:4.0.0

  USER root

  COPY Plugin-x.y.0.zip .
  RUN bin/csconfig plugins install Plugin-x.y.0.zip \
    && rm Plugin-x.y.0.zip

  COPY ProfileExport-(*@\ProductVersion @*).export .
  RUN bin/csconfig profiles import -r ProfileExport-4.0.0.export \
    && rm ProfileExport-4.0.0.export

  USER convsrv
```

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](configure-profiles.mdx) using a Windows installation, [export it](configure-profiles.mdx#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 file **ProfileExport-‹x›.‹y›.‹z›.export** (where **‹x›**.**‹y›**.**‹z›** is the version number of the service) containing the exported profiles must be made available in the container. To import the profiles on service startup, you need to set the `IMPORT_PROFILES` environment variable.

## Import profiles only
This simple profile configuration imports the file **ProfileExport-‹x›.‹y›.‹z›.export** only, which is typically sufficient.

Bind `ProfileExport-‹x›.‹y›.‹z›.export` 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=C:\path\to\ProfileExport-3.11.0.export,\
           dst=/etc/convsrv/ProfileExport.export,readonly" \
  -e IMPORT_PROFILES=/etc/convsrv/ProfileExport.export \
  -e LICENSEKEY=4H-V4-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \
  pdftoolsag/conversion-service:3.11.0
```

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 **ProfileExport-‹x›.‹y›.‹z›.export** and all references files to the directory `configuration`.
4. Create a volume `\convsrv-etc-‹x›.‹y›.‹z›` containing all configuration files from `configuration`:

```
docker volume create --name convsrv-etc-3.11.0
docker run --rm \
  --mount "type=bind,src=c:\path\to\configuration,dst=/source" \
  --mount "type=volume,src=convsrv-etc-3.11.0,dst=/etc/convsrv" \
  alpine \
  ash -c "cp /source/* /etc/convsrv/"
```

5. The folder `configuration` is not required anymore and can be deleted.
6. Run the image. Mount the volume `\convsrv-etc-‹x›.‹y›.‹z›` and set the environment variable **IMPORT_PROFILES** to activate the profile import:

```
docker run -dp 13033:13033 --network conversion-service \
  --mount "type=volume,src=convsrv-etc-3.11.0,dst=/etc/convsrv,readonly" \
  -e IMPORT_PROFILES=/etc/convsrv/ProfileExport-3.11.0.export \
  -e LICENSEKEY=4H-V3-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX \
  pdftoolsag/conversion-service:3.11.0
```

## 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

import useBaseUrl from '@docusaurus/useBaseUrl';

A profile is a structured, workflow-specific set of configuration settings. Each [workflow](../workflows/README.mdx) 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](configure-profiles-docker.mdx)**.
:::

## 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
It is recommended to export the profiles to a file named `ProfileExport-‹x›.‹y›.‹z›.export`, where `‹x›.‹y›.‹z›` is the version number of the service, e.g. `ProfileExport-3.11.0.export`.
:::

---

## Configure digital signature

import PenIcon from '/img/pen-solid.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';

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](/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 PDF/A-2](../../workflows/pdfa_2.mdx)
    - [Archive PDF/A-3](../../workflows/pdfa_3.mdx)
    - [Invoice](../../workflows/invoice.mdx)
    - [Sign](../../workflows/sign.mdx)

    :::caution
    Sign workflow is not removing 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 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](./set-up-signature/provider-globalsign)
    - [Configure PKCS#11 signature](./set-up-signature/provider-pkcs11)
    - [Configure Swisscom Signing Service signature](./set-up-signature/provider-swisscom)
    - [Configure Windows 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](/docs/pdf-tools-sdk/sign-and-secure/sign/signature-appearance/) in the Pdftools SDK documentation. 
:::

---

## Cryptographic providers

import useBaseUrl from '@docusaurus/useBaseUrl';

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](./provider-globalsign.mdx) (Online Service)
    - PADES-B-LT/LTA
- [PKCS#11](./provider-pkcs11.mdx) (Hardware Module)
    - PADES-B-T
    - PADES-B-LT/LTA
- [Swisscom](./provider-swisscom.mdx) (Online Service)
    - PADES-B-T 
    - PADES-B-LT/LTA 
    - On-Demand
- [Windows](./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)](/docs/pdf-tools-sdk/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

import useBaseUrl from '@docusaurus/useBaseUrl';

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 recovation 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](./README.mdx#signature-level) for more information.

---

## GlobalSign Digital Signing Service

import useBaseUrl from '@docusaurus/useBaseUrl';

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](./README.mdx#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](./README.mdx#trust-store) is a general settings among online signature providers.

#### Address

The service endpoint URL.

---

## PKCS#11

import useBaseUrl from '@docusaurus/useBaseUrl';

The PKCS#11 provider creates a session with a cryptographic device (fore 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 recovation 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](./README.mdx#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

import useBaseUrl from '@docusaurus/useBaseUrl';
import InfoCirlce from '/img/info-circle.svg';

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](./README.mdx#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](./README.mdx#signature-level) for more information.

#### Add revocation information

Whether to add recovation 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

import useBaseUrl from '@docusaurus/useBaseUrl';
import RightToBracket from '/img/right-to-bracket-solid.svg';
import PenIcon from '/img/pen-solid.svg';

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](../workflows/stamping.mdx)**.
:::

## 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 PDF/A-2 workflow](../workflows/pdfa_2.mdx), [Conversion](../workflows/conversion.mdx), or [Dossier](../workflows/dossier.mdx), or [other workflows](../workflows/README.mdx), and review available placeholders under the **Job and document options** header.

---

## Set up using the Configurator

import useBaseUrl from '@docusaurus/useBaseUrl';

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 temporay 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](configure-docker-container.mdx).
:::

## 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 [Convert files using local Microsoft Office installation](office-conversion.mdx#convert-files-using-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](../integrate/rest-api.mdx#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](../integrate/shell-client.mdx) and the [REST API](../integrate/rest-api.mdx).

## 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](../integrate/shell-client.mdx) refuse to connect. This hinders correct operation of many components, including the Configurator GUI or the [Connection configuration](configure-connections.mdx).
- A **trusted host certificate**.

To activate the HTTPS for [REST input JSON](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-json) and [REST input plain HTTP](../integrate/connectors/rest-connectors/rest-input-connectors.mdx#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](office-conversion.mdx).

## Log directory
The directory where all log files are written to. This includes the log files of the service (see [Service log](../monitor/service-log.mdx)), 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](../monitor/statistics.mdx) 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 datebase 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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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**).

![Basic conversion process](/img/workflow_details.png)

#### 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](../integrate/README.mdx)**.

---

## Convert Microsoft Office files

import GearSolid from '/img/gear-solid.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';

The Conversion Service uses Microsoft Office applications to process jobs containing Word, Excel, and PowerPoint documents. Select one of the following two options when configuring the Microsoft Office file conversion in the Conversion Service Configurator:
- Conversion with a [local Microsoft Office installation on the same server](#convert-files-using-local-microsoft-office-installation).
- Conversion using the [Office for the web service](#convert-using-the-office-for-the-web-service).

These options differ in configuration parameters, output quality, and performance. Both options extract embedded documents from Office documents in Open XML format (for example, DOCX, XLSX, PPTX) in a destructuring step before conversion. Macro instructions are disabled in all cases.

## Choose a Microsoft Office conversion method

To ensure high-quality conversion with accurate layout and visual fidelity, the Conversion Service offers two Microsoft-based processing options: a local Microsoft Office installation or the Office for the web service in Microsoft Azure Cloud. Both options deliver equally high conversion quality, with no significant differences identified in detailed comparisons.

Use the **[local Microsoft Office installation](#convert-files-using-local-microsoft-office-installation)** if you:
- Require high performance. Cloud conversion may involve significant overhead for uploading and downloading file contents.
- 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.
- Handle macro-enabled files (XLTM, PPTM, WordML).
- 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-premises 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 **[Convert using the Office for the web service](#convert-using-the-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're deploying the Docker version in production.
- You prefer lower setup and maintenance overhead.

---

## Convert files using local Microsoft Office installation

:::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 2019* (64-bit) |
| Office 2021 (64-bit) |
| Office 2024 (64-bit) |
| Microsoft 365 (64-bit) |

_* The Pdftools support for Microsoft Office 2019 will end in October 2025._

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 2019 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**.
![Windows Defender in Configurator](/img/config_windowsDefender.png)

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 **Conversion Service** tab, and then scroll to the  **Configuration** section.
    
    
    
1. Next to the **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 **Conversion Service** tab, and then scroll to the  **Configuration** section.
    
    
    
1. Next to the **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 of the Conversion Service 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**.

## Convert using the 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 **Conversion Service** tab, and then scroll to the  **Configuration** section.
    
    
    
1. Next to the **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

1. Enable **Office Conversion** in the [Processing Steps section of your profile](configure-profiles.mdx#exporting-profiles). Note that this option is active by default.
1. Create a persistent volume (for example, `convsrv-etc`) to store the authentication token cache.
    ```bash
    docker volume create --name convsrv-etc
    ```
1. Create the token cache directory and set permissions. Mount the volume, create the `TokenCaches` folder, and give 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 to:
    ```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. To start the Docker container, mount the token cache volume and set the required environment variables.
    ```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 environment variables **SERVICE__OFFICE__TYPE** and **SERVICE__OFFICE__USERNAME** according to the configured user and office type.

## Troubleshooting

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)

### Configuration errors

The following sections include the warnings and errors that you encounter inside the Configurator during configuration and possible solutions.

###### Microsoft Office is not installed

Click to expand for more details and solution:

![Office not installed](/img/troubleshooting-office-not-installed.png)
Solution: 
The conversion of Word, Excel, and PowerPoint documents to PDF requires an installation of Microsoft Office on the same server where the Conversion Service is installed. Install a compatible Microsoft Office version (see compatible Microsoft Office versions).

###### 3-Heights Document Converter installation detected

Click to expand for more details and solution:

![Office DCB](/img/troubleshooting-office-dcv-installed.png)

Solution: 
A parallel operation of the Conversion Service and the 3-Heights Document Converter on the same server is not recommended because the Office configurations of the two services interfere and break each other.

###### User validation failed

Click to expand for more details and solution:

![User validation failed](/img/troubleshooting-office-domain-user-domain-not-found.png)

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

Click to expand for more details and solution:

![Trust relationship failed](/img/troubleshooting-office-domain-connection-error.png)

Solution: 
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

Click to expand for more details and solution:

![Office configuration in Configurator](/img/troubleshooting-office-configuration-problem.png)

Solution:
This message can occur when a setting related to the Office Configuration was changed after the Office User was configured. Try to configure the Office user again. If the problem persists or another error occurs, contact Support.

###### The user name or password is incorrect when using a domain user account

Click to expand for more details and solution:

The Office conversion suddenly stops working when using a [domain user account](#convert-files-using-local-microsoft-office-installation).
In this case, the error is usually caused by a password group policy that forces password change at a regular interval. 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 Microsoft Office application use.  

###### The document is corrupt or a pop-up dialog window blocks the conversion process

Click to expand for more details and 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 was observed for a certain amount of time. If the error was triggered by a pop-up dialog box that is blocking the conversion process, the problem may sometimes be resolved by opening and editing the document manually. 

###### The application WINWORD exceeded the memory limit of 2048 MB

Click to expand for more details and 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 during conversion. This limit is a precaution set by the Conversion Service 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)

Click to expand for more details and solution:

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.

Click to expand for more details and solution:

This error occurs when the Trust Center settings block the file.
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). You need to restart the service after performing this change.

###### Excel conversion fails with a “Generic” error (COM exception 0x800a03ec)

Click to expand for more details and solution:

This error may be caused by the printer spooler or Microsoft Printer. The printer spooler is required for Office conversion. 

If you encounter this error, check:
- The Printer Spooler service is not disabled.
- [Install or reinstall the Microsoft Printer (Print to PDF)](https://answers.microsoft.com/en-us/windows/forum/all/how-to-add-or-reinstall-the-microsoft-pdf-printer/70377c34-e50a-42be-b9f3-92345d6e25df).

###### The server process could not be started because the configured identity is incorrect (COM exception 0x8000401a)

Click to expand for more details and solution:

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.

1. Use configuration.office repair CLI command 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)

Click to expand for more details and solution:

This error may occur after you configure 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.*

1. Restart the machine.

---

## Configure conversion of redlined Microsoft Word documents

import PenIcon from '/img/pen-solid.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';

Learn how to set up the Conversion Service to convert Microsoft Word documents with tracked changes (revisions, also called redlining) to PDF.

## 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

To enable the conversion of documents with tracked changes, 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

import DocCardList from '@theme/DocCardList';

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

import DocCardList from '@theme/DocCardList';

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](./simple-api.mdx) getting started for more information.

### Advanced API

The examples of Advance API use cases include the following:

- Merge hundreds of documents into a single PDF using the Dossier 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](./advanced-api.mdx) 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](../../api/README.mdx) 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](../windows-server.mdx) or [Conversion Service in Docker](../docker.mdx) 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](pathname:///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:

![Job processing sequence](/img/job-processing-sequence.png)

:::info
To learn more about the Advanced API, review **[Integrate through Advanced API](../../integrate/rest-api.mdx)** page and [Advanced API references](../../api/advanced-api/advanced-api.info.mdx).
:::

---

## Get started with Simple API

import useBaseUrl from '@docusaurus/useBaseUrl';
import RightToBracket from '/img/right-to-bracket-solid.svg';
import Spinner from '/img/spinner.svg';

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](../windows-server.mdx) or [Conversion Service in Docker](../docker.mdx) 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/ProfileExport-6.1.0.export
            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
            - C:/Users/john-doe/Desktop/ProfileExport-6.1.0.export:/etc/convsrv/ProfileExport-6.1.0.export
```

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/ProfileExport-6.1.0.export
            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
            - C:/Users/john-doe/Desktop/ProfileExport-6.1.0.export:/etc/convsrv/ProfileExport-6.1.0.export
    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"
```

## 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](pathname:///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](pathname:///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](../../api/simple-api/pdf-a-2-profile-rest-input-json.api.mdx).
:::

## Convert file using custom configuration

In the [Conversion Service on Windows Server](../windows-server.mdx) or [Conversion Service in Docker](../docker.mdx) 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 on **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 preconfigured 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 on **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 preconfigured 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](../../api/simple-api/pdf-a-2-profile-rest-input-json.api.mdx).
:::

## API references

Get more details about the Simple API. Review the API references on the [Simple API](../../api/simple-api/simple-api.info.mdx) references page.

---

## Conversion Service in Docker

import RightToBracket from '/img/right-to-bracket-solid.svg';
import ThreeDots from '/img/ellipsis-vertical-solid.svg';
import DownloadNonPadded from '/img/download-nopadding.svg';
import GetTrialLicense from '/src/modules/procedure/proc_cs-trial-license.mdx';
import RequestFullLicense from '/src/modules/procedure/proc_cs-full-license.mdx';
import useBaseUrl from '@docusaurus/useBaseUrl';

Learn how to run the Conversion Service in Docker.

## 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](../README.mdx#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

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 **Product kits** section, find the `ConversionService-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `ConversionService-5.7.1.8691.msi`, depends on the version you are installing.
    
    
    
    Ensure to download `ConversionService-VERSION_NUMBER.msi` **not** `ConversionService-Client-VERSION_NUMBER.msi` due to the focus of this guide.
1. Open the `ConversionService-VERSION_NUMBER.msi` installer and proceed with the guided installation.**[^1]**
1. In the My PDF Tools Portal, go to [Licenses & Kits](https://my.pdf-tools.com/en/mypdftools/licenses-kits/), and then click **Conversion Service**.
1. In the **License** section, click the **LICENSE** button to reveal the license key, and then click **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 `ConversionService-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](/docs/licenses/products/conversion-service-license/).
- [Set up the Licensing Gateway Service](/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 upper right 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/ProfileExport-5.7.2.export
            ports:
                # Exposes port 13033 for external communication.
                - "13033:13033"
            volumes:
                - C:/Users/john-doe/Desktop/ProfileExport-5.7.2.export:/etc/convsrv/ProfileExport-5.7.2.export
    ```
    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.
    - `C:/Users/john-doe/Desktop/ProfileExport-5.7.2.export`: The file path and the name of the exported profile on Windows.
    - `ProfileExport-5.7.2.export`: Filename of your export file.
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, Calibri fonts are selected for text stamps within the Configurator 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**.

## Configure Microsoft Office file conversion

Learn how to configure Microsoft Office file conversion in Docker with the Microsoft Office for Web.

:::tip Prerequisites
To enable Microsoft Office file conversion in Docker, you need:
- Account for Microsoft Office for Web.
- Conversion Service profile with Microsoft Office conversion enabled. Most profiles have this conversion enabled, review [Configure and export a profile](#configure-and-export-a-profile).
:::

1. Edit the `docker-compose.yaml` as follows:
    ```yaml
    volumes:
        vol-conversion-srv-app-data: {}
    services:
        conversion-service:
            # Conversion Service image. Converts files to PDF format.
            image: pdftoolsag/conversion-service:IMAGE_VERSION
            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/ProfileExport-5.7.2.export
                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
                - C:/Users/john-doe/Desktop/ProfileExport-5.7.2.export:/etc/convsrv/ProfileExport-5.7.2.export
    ```
    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.
    - `YOUR_OFFICE_USERNAME`: Username of the account you want to use for Microsoft Office conversion.
    - `C:/Users/john-doe/Desktop/ProfileExport-5.7.2.export`: The file path and the name of the exported profile on Windows.
    - `ProfileExport-5.7.2.export`: Filename of your export file.
1. In the directory where the `docker-compose.yaml` is located, run the following command:
    ```bash
    docker compose up -d
    ```
1. In the same directory, run:
    ```bash
    docker ps
    ```
1. Copy the container ID where you run the Conversion Service. This ID can have a form similar to: `09d8dcaiel23`
    :::note
    The `docker ps` also displays the container name. Every time you run the `docker compose up -d`, a new ID is generated, and you need to copy this ID again.
    :::
1. Grant the Conversion Service user access to the volume data inside the container by running the following command:
    ```bash
    docker exec -u root CONTAINER_ID_OR_NAME chown convsrv:convsrv /etc/convsrv/
    ```
    - Replace `CONTAINER_ID_OR_NAME` with your container's name **or** ID.
1. Run the following command to configure the Microsoft Office user:
    ```bash
    docker exec CONTAINER_ID_OR_NAME ./bin/csconfig office webinit
    ```
    - Replace `CONTAINER_ID_OR_NAME` with your container's name **or** ID.

    The output is a message with the next steps specified. Review the example below:
    
    
    
1. Open the provided link, and then enter the code.
1. Log in with the username that you added as the value of the `SERVICE__OFFICE__USERNAME` environment variable in the first step of this configuration.
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 Microsoft Office enabled. 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**.

## Next steps

For more details about Docker configuration, see [Set up the service in Docker](../configure/configure-docker-container.mdx) 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](../configure/README.mdx). 
- Adapt the default profile or [create a new profile for a workflow](../configure/configure-profiles.mdx).
- [Create a new workflow](../workflows/README.mdx)

There are several ways you can [integrate the Conversion Service](../integrate/README.mdx) into your system:

- [Shell client](../integrate/shell-client.mdx) 
- [REST API](../integrate/rest-api.mdx)

### 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 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](../workflows/pdfa_1.mdx#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 Framework 4.7+](https://dotnet.microsoft.com/en-us/download/dotnet-framework)
    - [.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 Windows Server

import RightToBracket from '/img/right-to-bracket-solid.svg';
import RightFromBracket from '/img/right-from-bracket-solid.svg';
import ThreeDots from '/img/ellipsis-vertical-solid.svg';
import GearSolid from '/img/gear-solid.svg';
import DownloadNonPadded from '/img/download-nopadding.svg';
import GetTrialLicense from '/src/modules/procedure/proc_cs-trial-license.mdx';
import RequestFullLicense from '/src/modules/procedure/proc_cs-full-license.mdx';
import InstallAndActivateLicense from '/src/modules/procedure/proc_cs-install-activate-license.mdx';
import useBaseUrl from '@docusaurus/useBaseUrl';

Learn how to install and use the Conversion Service on Windows Server to automate document processes.

## Prerequisites

- You have a Windows Server machine with the following dependencies installed:
    - [.NET Framework 4.7+](https://dotnet.microsoft.com/en-us/download/dotnet-framework)
    - [.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)

## 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 **Product kits** section, find the `ConversionService-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `ConversionService-5.7.1.8691.msi`, depends on the version you are installing.
    
    
    

Available installers explained:
- **Windows Server**: The `ConversionService-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: `ConversionService-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 `ConversionService-Client-VERSION_NUMBER.msi` installer on the same machine where you installed the Conversion Service Configurator with the `ConversionService-VERSION_NUMBER.msi`. Conflicting installations can cause the Conversion Service to stop functioning correctly.
:::

## 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. These files are saved by default in the `C:\ProgramData\Pdftools\Conversion Service\Logs` folder. The Conversion Service uses several different log files:
- `ConversionService-Service.log`: Main service log file (current).
- `ConversionService-Service-DATE.log`: Past service logs.
- `ConversionService-Connections.log`: For any [Connector](../integrate/connectors/README.mdx) 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](../monitor/service-log.mdx) 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 upper right corder of the PDF file, scroll down to **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 centre 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, Calibri fonts are selected for text stamps within the Configurator by default, but you must install the Calibri font family to finish the processing successfully.
:::

You learned to configure your custom profile for Archive PDF/A-2 workflow, and add a configured stamp on converted documents.

### Configure Microsoft Office file conversion

To convert Microsoft Word, Excel, and PowerPoint files to PDF files with the Conversion Service, you need a valid Microsoft 365 for Business license. For Microsoft Office file conversion, we recommend using the English (en-US) version of the operating system. To enable Microsoft Office file conversion in the Conversion Service, issue the following steps:

1. In the **Conversion Service Configurator**, go to **Conversion Service** tab, and then scroll to the  **Configuration** section.
    
    
    
1. Next to the **Office Conversion**, click **Configure**, from the displayed window, select **Local Office Installation and Automatically Create a User Account**, and then click **Next**.
    
    
    

    This option creates a user account with pre-configured settings. For detailed information about all available configuration options, review [Convert Microsoft Office files](../configure/office-conversion.mdx).

1. Click **Apply**, and then in the **Changes detected** dialog box, click **Save & Restart Service**.
1. In the **PDF Client for Conversion Service**, click the **Profile** drop-down list, and then select a profile where Office conversion is used. For example, **awesome-test-profile**.
1. Drag a Microsoft Office file to the  **Input** box. 
1. Click **Convert**.

You learned how to configure Microsoft Office file conversion in the Conversion Service.

:::note
If you experience any issues during configuration or conversion, refer to the [Troubleshooting](../configure/office-conversion.mdx#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 a file is included in 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: **my-custom-watched-folder**.
1. Select **Archive PDF/A-2** as a workflow, and then select a profile. You can use the profile we have previously created 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 is designed to convert 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
file(s)** 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 `ConversionService-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 **Product kits** section, find the `ConversionService-Client-VERSION_NUMBER.msi` package, and then click **Download **. The exact filename, for example, `ConversionService-Client-5.7.1.8691.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 where the Conversion Service is installed.
        
        
        

For more configuration options for this client, review [PDF Client for Conversion Service](../integrate/gui-client.mdx) documentation.

## Next steps

You learned how to run the Conversion Service in Docker, 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](../configure/README.mdx). 
- Adapt the default profile or [create a new profile for a workflow](../configure/configure-profiles.mdx).
- [Create a new workflow](../workflows/README.mdx)

There are also several ways how to [integrate the Conversion Service](../integrate/README.mdx) into your system:

- [Watched folder and other connectors](../integrate/connectors/README.mdx)
- [Shell client](../integrate/shell-client.mdx) 
- [REST API](../integrate/rest-api.mdx)
- [GUI](../integrate/gui-client.mdx)

---

## Integrate the Conversion Service

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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:
 

  

- **[Shell client](shell-client.mdx)**: Recommended for integration using scripts. Suited for automated and manually triggered processing.
- **[REST API](rest-api.mdx)**: Web service interface. Recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application.
- **[Watched folder](connectors/folder-connectors.mdx)** 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](connectors/rest-connectors/README.mdx)** 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](connectors/email-connectors.mdx)** 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](gui-client.mdx)**: Easy-to-use graphical user interface. Recommended for testing and familiarizing yourself with the Conversion Service. Suited for manually triggered processing only.
- **[Plugins](../configure/configure-plugins.mdx)**: 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 `ConversionService-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 ConversionService.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 `ConversionService-Client.msi`. 
This adds a Conversion Service button to Microsoft Word, Outlook, Excel, and PowerPoint application toolbars.

- **[Shell client](shell-client.mdx)**: Recommended for integration using scripts. Suited for automated and manually triggered processing.
- **[REST API](rest-api.mdx)**: Web service interface. Recommended for integrating into your existing application (Enterprise Application Integration). Suitable for automated processing from within your application.
- **[Watched folder](connectors/folder-connectors.mdx)** 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](connectors/rest-connectors/README.mdx)** 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.

:::tip
To integrate with an existing system processes, you can [configure your Conversion Service](../configure/configure-connections.mdx) to use [connectors](connectors/README.mdx) 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](../../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](folder-connectors.mdx#watched-folder)**: Converts all files that are placed into a configurable input directory. After the conversion is finished, the files are deleted.
- **[Output folder](folder-connectors.mdx#output-folder)**: Copies files into a configurable output directory.
- **[Create text file](folder-connectors.mdx#create-text-file)**: Creates a text file in a configurable directory.

## Email connectors

- **Watched mailbox** ([IMAP](email-connectors.mdx#watched-mailbox-imap) or [Exchange Online](email-connectors.mdx#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](email-connectors.mdx#output-mailbox-imap) or [Exchange Online](email-connectors.mdx#output-mailbox-exchange-online)): Copies files to a configurable mailbox.
- **Send email** ([SMTP](email-connectors.mdx#send-email-smtp) or [Exchange Online](email-connectors.mdx#send-email-exchange-online)): Sends an email to a configurable recipient.

## REST connectors

- **REST input** ([Plain HTTP](rest-connectors/rest-input-connectors.mdx#rest-input-plain-http)  or [JSON](rest-connectors/rest-input-connectors.mdx#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](./rest-connectors/rest-output-connectors.mdx)**: Posts files as a multipart/form-data request to a configurable output URL

## Other connectors
- **[Execute command](other-connectors.mdx#execute-command)**: Performs a configurable command on files.

---

## 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.

## 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.

## 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](rest-connectors/README.mdx) connector.
- Query parameters from the [REST Input](rest-connectors/README.mdx) 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](rest-connectors/README.mdx) connector.
- Query parameters from the [REST Input](rest-connectors/README.mdx) 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.

## Placeholders in Send Email connectors

You can use placeholders in the recipient, subject, and body fields of the [Send Email (Exchange Online)](#send-email-exchange-online) and [Send Email (SMTP)](#send-email-smtp) 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](../../getting-started/windows-server.mdx#configure-a-watched-folder) section in the getting started guide.
- In Docker Compose, review [Configure containers using docker compose](../../configure/configure-docker-container.mdx#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](other-connectors.mdx#execute-command) connector or as placeholders in the URL setting of the [REST Output](rest-connectors/rest-output-connectors.mdx) 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 perform 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

import DocCardList from '@theme/DocCardList';

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)

import useBaseUrl from '@docusaurus/useBaseUrl';

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](../../../getting-started/api/simple-api.mdx)
- [Simple API references](../../../api/simple-api/simple-api.info.mdx)
- [Simple API Postman collection](pathname:///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](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json) or the [Simple API reference](../../../api/simple-api/simple-api.info.mdx).

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](../../../getting-started/api/simple-api.mdx#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](../../../configure/configure-job-and-document-options.mdx) 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](../other-connectors.mdx#execute-command) connector.
    - Placeholders in the URL setting of the [REST Output](rest-output-connectors.mdx) 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](../../../configure/configure-job-and-document-options.mdx) 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](../other-connectors.mdx#execute-command) connector.
    - Placeholders in the URL setting of the [REST Output](rest-output-connectors.mdx) 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](../../../api/simple-api/simple-api.info.mdx).
- The [Simple API Postman collection](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json).
- The [Simple API getting started guide](../../../getting-started/api/simple-api.mdx).

---

## 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

import useBaseUrl from '@docusaurus/useBaseUrl';
import ThreeDots from '/img/ellipsis-vertical-solid.svg';

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](../getting-started/windows-server.mdx#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 blackilist 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](shell-client.mdx) and the [watched folder](connectors/folder-connectors.mdx#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](../configure/configure-docker-container.mdx#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 787](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](../api/advanced-api/advanced-api.info.mdx). 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](pathname:///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 return 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 Services works](../configure/how-cs-works.mdx) or the specific [workflows](../workflows/README.mdx) such as [PDF/A 2](../workflows/pdfa_2.mdx) or [Conversion](../workflows/conversion.mdx) workflows.

To schedule a job and retrieve its result, the sequence is as follows:

![Job processing sequence](/img/job-processing-sequence.png)

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](../api/advanced-api/get-service-status.api.mdx).

### 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](../api/advanced-api/list-jobs.api.mdx).

### 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](../api/advanced-api/list-workflows.api.mdx).

---

## 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](rest-api.mdx).
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. pdfclient -s *.ext C:\path\to\output`
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](installation.mdx#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](overview.mdx#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](overview.mdx#high-level-architecture) and [integration options](overview.mdx#integrations).

## Formats supported by the Conversion Service

The [input](overview.mdx#supported-input-formats) and [output formats](overview.mdx#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](overview.mdx#job-and-document-processing)** in the Conversion Service.

Depending on the specific workflow, [nested files and attachments](overview.mdx#supported-nested-files-and-attachments) can be processed by the Conversion Service.

## Installing the Conversion Service

The Conversion Service has an [MSI installation package](../update/README.mdx) to install the service on your infrastructure.

There are differences in the [default folder locations](installation.mdx#default-folder-locations), and how [log files](installation.mdx#log-files) and [configuration files](installation.mdx#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](../configure/configure-profiles.mdx) 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](job-processing.mdx).

## 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](integrate/README.mdx) offered with the 3-Heights® Document Converter are available also for the Conversion Service. See [Integrations](integrate/README.mdx).

:::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](../api/advanced-api/get-job-result.api.mdx) 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](../api/advanced-api/get-job-result.api.mdx) 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](../api/advanced-api/get-job-result.api.mdx) 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](../api/advanced-api/get-job-result.api.mdx) 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](../api/advanced-api/get-job-result.api.mdx) 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](../monitor/service-log.mdx)**.
:::

:::tip
For more information on the `events`, `dataId`, and `dataPart` schemas, see the **[Get job result](../api/advanced-api/get-job-result.api.mdx)** 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](../update/README.mdx)**.
:::

## 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 2016, 2019, 2022 (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 2016 (64 Bit), 2019 (64 Bit), 2021 (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 Framework 4.7 + .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](../update/README.mdx)**.

## Log files

All verbose information is written to the [Service log files](../monitor/service-log.mdx) 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](../configure/configure-win-service.mdx) 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](../configure/configure-win-service.mdx)**.

|                                  | Conversion Service | 3-Heights® Document Converter          |
| -------------------------------- | ------------------ | -------------------------------------- |
| General service settings         |                    | `O2PSRV.exe.config` `appsettings.json` |
| Worker settings                  |                    | `O2PWSC.exe.config`                    |
| Job/Document processing settings | `Workflows.xml`    | `O2PWSC.ini`                           |
| Watched Folder settings          | `Connections.xml`  | `O2PWFS.ini`                           |
| Mail Folder settings             |                    | `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](../configure/office-conversion.mdx)**.

---

## 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](../../integrate/shell-client.mdx).

## 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](../../integrate/rest-api.mdx).
- **Single-call SOAP web service interface**: This interface has been replaced by [REST input connectors](../../integrate/connectors/rest-connectors/README.mdx) 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](../../integrate/gui-client.mdx) to convert your files from the desktop.

| Integration type                                         | Conversion Service | 3-Heights® Document Converter |
| -------------------------------------------------------- | ------------------ | ----------------------------- |
| [GUI client application](../../integrate/gui-client.mdx)    | Yes                | Yes                           |
| [Command line client application](CLI.mdx)               | Yes                | Yes                           |
| [Watched folders](watched-folders.mdx)                   | Yes                | Yes                           |
| [Mail folders](watched-mail-folders.mdx)                 | Yes                | Yes                           |
| [Send email](watched-folders.mdx)                        | Yes                | Yes                           |
| [Web service interface (REST)](../../integrate/rest-api.mdx) | 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](../../update/README.mdx) using the Client MSI installation package (`ConversionService-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](../../configure/office-conversion.mdx) 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](../../integrate/connectors/README.mdx).

:::tip
For more information about watched folders in the Conversion Service, see **[Folder Connectors](../../integrate/connectors/folder-connectors.mdx)**.
:::

## 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                                                                                                  |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| ![Add Watched Folder in the 3-­Heights® Document Converter](/img/DCV_watched-folder.png) | ![Add watched folder in the Integration tab of the Conversion Service Configurator](/img/config_watched-folder.png) |

4. Configure the [desired watched folder](../../integrate/connectors/folder-connectors.mdx).

| 3-­Heights® Document Converter                         | Conversion Service                                                                       |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| ![Watched folder](/img/DCV_watched-folder-options.png) | ![Configure the settings for the watched folder](/img/config_watched-folder-options.png) |
| 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](../../workflows/README.mdx) are taken into account when converting documents placed in the watched folder.

| 3-­Heights® Document Converter                               | Conversion Service                                              |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| ![Job options for watched folders](/img/DCV_job-options.png) | ![Job options for watched folders](/img/config_job-options.png) |

## 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](../../integrate/connectors/folder-connectors.mdx#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                                                                                                            |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| ![Log file location](/img/DCV_error-log.png) | ![Log files for watched folders](/img/config_log-files.png) ![Log files for watched folders](/img/config_log-files2.png) |

## 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](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#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                                               |
| ----------------------------------------------------- | -------------------------------------------------------------- |
| ![Recursive search option](/img/config_recursive.png) | ![Recreate folders option](/img/config_recreate-structure.png) |

## 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](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#output-folder): _Job Status = Success_ and _Fileset = Originals_ | For `true`, **don't** configure an output folder for these conditions.                                                                                                                                                  |
| `AutoDeleteAll`                               | [Output Folder connector](../../integrate/connectors/folder-connectors.mdx#output-folder): _Job Status = Error_ and _Fileset = Originals_   | For `true`, **don't** configure an output folder for these conditions.                                                                                                                                                  |
| `JobPrefix`                                   | [Output Folder connector](../../integrate/connectors/folder-connectors.mdx#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](../../monitor/service-log.mdx#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](../../configure/configure-win-service.mdx#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](../../configure/configure-connections.mdx) tab.                                                                                                     |
| `Thread`                                      | Configured watched folder                                                                                                                   | All configured Watched Folders listed in the [Integration](../../configure/configure-connections.mdx) 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](../../configure/configure-profiles.mdx). [Document options](../overview.mdx#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](../../configure/configure-profiles.mdx)                                                                                                                                            | Job options are configured in the dedicated profile. See [Job options](../overview.mdx#job-and-document-processing)                                                                                                                                                           |
| `-l` create error log                             | [Create Text File](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#output-folder) connector: _Job Status -> Success or SuccessOrWarning_                                                                   | Add an output folder connector with the corresponding conditions.                                                                                                                                                                                                             |
| `-of` specify failed directory                    | [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#output-folder) connector: _Job Status -> Success; File Set -> Originals_                                                                | Add an output folder connector with the corresponding conditions.                                                                                                                                                                                                             |
| `-ow` ignore warnings                             | [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../configure/configure-profiles.mdx): _Conversion Settings -> Warnings_ |
| `-owf` warnings output folder                     | [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#output-folder) connector: _Job Status -> Success_                                                                                       | Create additional output folder within your watched folder                                                                                                                                                                                                                    |
| `-o2` force succeeded                             | [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#watched-folder): _Recursive_ and [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#watched-folder)                                                                                                                        | Configure the input folder within the watched folder                                                                                                                                                                                                                          |
| `-wfi` ignore files with certain extensions       | [Watched Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/README.mdx).
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)](../../integrate/connectors/email-connectors.mdx#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)](../../integrate/connectors/email-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#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)](../../integrate/connectors/email-connectors.mdx#output-mailbox-imap) or [Output Mailbox (Exchange Online)](../../integrate/connectors/email-connectors.mdx#output-mailbox-exchange-online) or [Output Folder](../../integrate/connectors/folder-connectors.mdx#output-folder) |
| Mail recipient (SMTP)                          | [Send Email (SMTP)](../../integrate/connectors/email-connectors.mdx#send-email-smtp) or [Send Email (Exchange Online)](../../integrate/connectors/email-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#output-folder)                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                               |
| File System Directory with _Completion Action_ | [Execute Command](../../integrate/connectors/other-connectors.mdx#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.

![Output folders](/img/DCV_output-folders.png)

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)](../../integrate/connectors/email-connectors.mdx#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)](../../integrate/connectors/email-connectors.mdx#send-email-smtp).
    - Configure the account settings and message properties.

6.  To configure a "Succeeded" folder, add an **Output** connector:
    - Select [Output Folder](../../integrate/connectors/folder-connectors.mdx#output-folder)
    - In File set, select _Originals_.

7.  To configure a "Failed" folder, add an **Output** connector:
    - Select [Output Folder](../../integrate/connectors/folder-connectors.mdx#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](../../integrate/connectors/folder-connectors.mdx#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](../../configure/configure-connections.mdx) 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](../../integrate/connectors/email-connectors.mdx)** (Exchange Online or IMAP) / [Watched Folder](../../integrate/connectors/folder-connectors.mdx#watched-folder)                                                                                                                                                                  |
| Output Folder (`-o`)           | Output connector: **[Output Folder](../../integrate/connectors/folder-connectors.mdx#output-folder)** / **[Output Mailbox](../../integrate/connectors/email-connectors.mdx)** (Exchange Online or IMAP) / **[Send Email](../../integrate/connectors/email-connectors.mdx#send-email)** (Exchange Online or SMTP) with **Job Status: Success** and **File Set: Results**                                                              |
| Succeeded Folder (`-os`)       | Output connector: **[Output Folder](../../integrate/connectors/folder-connectors.mdx#output-folder)** / **[Output Mailbox](../../integrate/connectors/email-connectors.mdx)** (Exchange Online or IMAP), **[Send Email](../../integrate/connectors/email-connectors.mdx#send-email)** (Exchange Online or SMTP) with **Job Status: Success** and **File Set: Originals**                                                             |
| Failed Folder (`-of`)          | Output connector: **[Output Folder](../../integrate/connectors/folder-connectors.mdx#output-folder)** / **[Output Mailbox](../../integrate/connectors/email-connectors.mdx)** (Exchange Online or IMAP), **[Send Email](../../integrate/connectors/email-connectors.mdx#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](../overview.mdx#job-and-document-processing)                                                                                                                                                                                                                                                                    |
| Document options (`-b`)        | Configure workflow and profile settings, see [Job and document options](../overview.mdx#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](../../workflows/README.mdx) are taken into account when converting with this Watched Mailbox.

| 3-­Heights® Document Converter                | Conversion Service                               |
| --------------------------------------------- | ------------------------------------------------ |
| ![Job options](/img/DCV_job-options-mail.png) | ![Job options](/img/config_job-options-mail.png) |

---

## Job and document processing options

import PenIcon from '/img/pen-solid.svg';

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](../workflows/README.mdx): Profile setting **Compression and Optimization** (optional) -> **Optimization Profile** [Conversion Workflow](../workflows/conversion.mdx): 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](nested-files-attachments.mdx)|
| `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** Conversion 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](nested-files-attachments.mdx) | 
| `SELECTFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) | 
| `SKIPFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) |
| `SKIPFILES` | Profile setting **Conversion Settings** -> **Convert Mode for Child Documents** | Flexible rule-based configuration. See [Nested files and attachments](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) |
| `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](error-handling.mdx) |
| `ERRPAGE` | Feature not available | Error handling works differently in the Conversion Service  See [Errors & Warnings](error-handling.mdx) |
| `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](ocr.mdx) |
| `OCR.BITONAL` | Not configurable (automatic) | The service automatically determines the optimal setting for each page. See [OCR](ocr.mdx) |
| `OCR.EMBEDBARCODES` | Feature not available (`false`) | Barcode recognition is **not supported**.  See [OCR](ocr.mdx) |
| `OCR.ENGINE` | Profile setting **OCR Settings** (optional) -> **Engine** | Select type when adding an engine configuration. See [OCR](ocr.mdx) |
| `OCR.LANGUAGE` | Profile setting **OCR Settings** (optional) -> **Engine** -> **Languages** |  See [OCR](ocr.mdx) |
| `OCR.IMAGEMODE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Image Processing Mode** |  See [OCR](ocr.mdx) |
| `OCR.TEXTMODE` | Profile setting **OCR Settings** (optional) -> **Text** -> **Text Processing Mode** |  See [OCR](ocr.mdx) |
| `OCR.PAGEMODE` | Profile setting **OCR Settings** (optional) -> **Pages** -> **Page Processing Mode** |  See [OCR](ocr.mdx) |
| `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](ocr.mdx) |
| `OCR.REEMBEDIMAGE` | Not configurable (`false`) | The original appearance of the document is always preserved.  See [OCR](ocr.mdx) |
| `OCR.ROTATEPAGE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Correct Rotation** |  See [OCR](ocr.mdx) |
| `OCR.TAGGING` | Profile setting **OCR Settings** (optional) -> **Tagging** -> **Tagging Mode** |  See [OCR](ocr.mdx) |
| `PASSTHROUGH` | *Workflow Archive 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](nested-files-attachments.mdx) |
| `PDFA` | Workflow selection | Whether a PDF/A is produced depends on the selected workflow: `true` -> "Archive PDF/A-", `false` -> "Conversion". See [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDFA.ERROR` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](error-handling.mdx) and [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDFA.LOGDETAILS` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](error-handling.mdx) and [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDFA.LOGSUMMARY` | Not applicable | PDF/A conversion errors are handled the same way as all other types of errors and warnings. See [Errors & warnings](error-handling.mdx) and [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDFA.OCRMODE` | Profile setting **OCR Settings** (optional) -> **Images** -> **Image Processing Mode** |  Option `OCR.IMAGEMODE`, See [OCR](ocr.mdx) |
| `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](nested-files-attachments.mdx) |
| `PDFA.WARNDOWNGRADE` | Not applicable | The desired conformance level cannot be configured explicitly. See [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDFA.WARNUPGRADE` | Not applicable | the Conversion Service never upgrades the file to a different PDF/A standard. See [PDF-A and Conformance](pdfa-conformance.mdx) |
| `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](pdfa-conformance.mdx) |
| `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](nested-files-attachments.mdx) |
| `PDF.COMPLIANCE` | Workflow selection | The available workflows correspond to the settings `1AB`, `2AUB`, `3AUB` and `PDF`. See [PDF-A and Conformance](pdfa-conformance.mdx) |
| `PDF.DATE` | The creation date of the input document is used if available |  |
| `PDF.Embed` | *Invoice workflow*: Option **`DOC.ROLE`** | The role of each document has to be specified explicitly. See [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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](stamping.mdx) |
| `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 TIFF workflow: **Workflows & Profiles** -> **Archive TIFF** -> **Profile settings**  -> **Compression** -> **Bileval (B&W) Images** |  | 
| `TIFF.COMPR.CONTINOUS` | Archive TIFF workflow: **Workflows & Profiles** -> **Archive TIFF** -> **Profile settings**  -> **Compression** -> Available options are: RGB and YCbCr ImagesCMYK ImagesImages in LAB Color Space |  |
| `TIFF.COMPR.INDEXED` | Archive TIFF workflow: **Workflows & Profiles** -> **Archive TIFF** -> **Profile settings**  -> **Compression** -> **Images with a Color Palette** |  |
| `TIFF.COMPR.MRC` | Archive TIFF workflow: **Workflows & Profiles** -> **Archive 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 TIFF workflow: **Workflows & Profiles** -> **Archive 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` | *Invoice workflow*: Option **`DOC.ROLE`** | See [Nested Files & Attachments](nested-files-attachments.mdx) |
| `ATTACHMENTS:ADD` | Profile setting **Conversion Settings** -> **Collect Mode** -> **Type** -> **Email** | See [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) |
| `ATT.Description` | *Invoice workflow*: Option **`DOC.DESCRIPTION`** | See [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) | 
| `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](nested-files-attachments.mdx) |
| `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](nested-files-attachments.mdx) and [Mail Folders (Watched Mailboxes)](integrate/watched-mail-folders.mdx) |
| `ORIGINALNAME` | REST interface: Multipart header **`Content-Disposion`** |  |
| `AlternateText` | Feature not available |  |
| `LanguageTag` | Feature not available |  |
| `Outline` | *Dossier workflow*: Profile setting **Outline (Bookmarks)** -> **Document Outline** *Other workflows*: Not configurable (automatic) | [Nested Files & Attachments](nested-files-attachments.mdx) |
| `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.

![Conversion settings for Child mode](/img/config_convert-mode-attachments.png)

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 a 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**:

![Conversion settings for Collect mode](/img/config_collect-mode.png)

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.

---

## OCR

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 directly in the Conversion Service without the OCR Service for new installations. For details about the recommended configuration of the OCR engine through the Conversion Service, see [Configure OCR](../configure/configure-ocr.mdx) documentation.
:::

### Configure 3-Heights® OCR Service in the Conversion Service
You can activate OCR processing for the **archive** and **conversion** workflows.
The 3-Heights® PDF OCR Service must be configured and accessible through HTTP.

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 the desired workflow profile in which you want to activate the OCR.
3. Enable the **OCR Settings** processing step toggle.
4. Navigate to the now visible configuration section **OCR Settings**.
5. In **OCR Settings** section, click the **Add Item** button.
6. Select **3-Heights® OCR Service** as the OCR engine, and then click  **Next**.
7. The preset values are made for local OCR service. 
8. Optional: If the OCR service is on a different server, adjust the URL.
9. Click **Apply**.

You can configure multiple 3-Heights® OCR Services to distribute the OCR processing equally.

---

## 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](integrate/README.mdx)            | 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](integrate/README.mdx)                                                         | 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](integrate/office-integration.mdx), [GUI Client](integrate/gui-client.mdx), [Command Line Client](integrate/CLI.mdx) | Available as a separate installer.                                                                                                   |
| Linux/Docker image                                                                                                         | [Supported](../update/README.mdx), 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](job-processing.mdx#application-options) | [Profile settings](../configure/configure-profiles.mdx)      |
| [Job options](job-processing.mdx#job-options)                 | [Profile configuration](../configure/configure-profiles.mdx) |
| [Document options](job-processing.mdx#document-options)       | [Workflow-specific document options](../workflows/README.mdx)      |

## 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](ocr.mdx).                                                                                                                                                                  |
| OCR (Barcode recognition)                        | _No_               | _Yes_                         | See [OCR](ocr.mdx).                                                                                                                                                                  |
| Digital signatures                               | _Yes_              | _Yes_                         |                                                                                                                                                                                    |
| PDF compression and optimization                 | _Yes_              | _Yes_                         | Only predefined profiles supported.                                                                                                                                                |
| PDF linearization (fast web-view)                | _No_               | _Yes_                         | Linearization is not recommended as it can increase file size considerably and its effect is quite limited.                                                                        |
| Stamping                                         | _Partially_        | _Yes_                         | See [Stamping](stamping.mdx).                                                                                                                                                        |
| Metadata                                         | _Yes_              | _Yes_                         |                                                                                                                                                                                    |
| Electronic invoice embedding (ZUGFeRD, Factur-X) | _No_               | _Yes_                         |                                                                                                                                                                                    |
| Table of contents and title page generation       | _Yes_              | _No_                          | See [Dossier workflow](../workflows/dossier.mdx).                                                                                                                                    |
| 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](../configure/office-conversion.mdx).                              |
| 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](../configure/office-conversion.mdx).                              |
| WordML / WordprocessingML (XML)                                               | _Yes_              | _Yes_                         | Requires MS Word installed and properly licensed on the server. See [Convert Microsoft Office files](../configure/office-conversion.mdx).                              |
| MS Excel binary formats (XLS, XLT)                                            | _Yes_              | _Yes_                         | Requires MS Excel installed and properly licensed on the server. See [Convert Microsoft Office files](../configure/office-conversion.mdx).                             |
| 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](../configure/office-conversion.mdx).                             |
| SpreadsheetML (XML)                                                           | _Yes_              | _Yes_                         | Requires MS Excel installed and properly licensed on the server. See [Convert Microsoft Office files](../configure/office-conversion.mdx).                             |
| MS PowerPoint binary formats (PPT, PPS)                                       | _Yes_              | _Yes_                         | Requires MS PowerPoint installed and properly licensed on the server. See [Convert Microsoft Office files](../configure/office-conversion.mdx).                        |
| 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](../configure/office-conversion.mdx).                        |
| 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](../configure/office-conversion.mdx).                              |
| 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](pdfa-conformance.mdx).      |
| PDF/A-2         | _Yes_              | _Yes_                         | See [PDF/A and conformance](pdfa-conformance.mdx).      |
| PDF/A-3         | _Yes_              | _Yes_                         | See [PDF/A and conformance](pdfa-conformance.mdx).      |
| Plain PDF (1.x) | _Yes_              | _Yes_                         | See [Conversion workflow](../workflows/conversion.mdx). |
| TIFF            | _Yes_              | _Yes_                         | See [Archive TIFF](../workflows/tiff.mdx).     |

### 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](nested-files-attachments.mdx).

## Integrations

The Conversion Service offers multiple integration options such as, [watched folders](../integrate/connectors/README.mdx) and other connectors, a [REST API](../integrate/rest-api.mdx), and a [PDF GUI client](../integrate/gui-client.mdx).

| Integration                                                | Conversion Service      | 3-Heights® Document Converter |
| ---------------------------------------------------------- | ----------------------- | ----------------------------- |
| [GUI client application](../integrate/gui-client.mdx)      | _Yes_                   | _Yes_                         |
| [Command line client application](integrate/CLI.mdx)       | _Yes_                   | _Yes_                         |
| [Watched folders](integrate/watched-folders.mdx)           | _Yes_                   | _Yes_                         |
| [Mail folders](integrate/watched-mail-folders.mdx)         | _Yes_                   | _Yes_                         |
| [Send email](integrate/watched-mail-folders.mdx)           | _Yes_                   | _Yes_                         |
| [Web service interface (REST)](integrate/rest-api.mdx)     | _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](../configure/configure-docker-container.mdx) | _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 PDF/A-2 (default workflow)
- [**PDF/A-3**](#pdfa-3): Archive PDF/A-3
- [**PDF/A-1**](#pdfa-1): Archive PDF/A-1 (disabled by default)
- [**Plain PDF 1.X**](#plain-pdf-1x): Conversion

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](../workflows/README.mdx#archive-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](../workflows/pdfa_2.mdx)** 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](nested-files-attachments.mdx)**.
:::

### 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**.
    
![Warnings](/img/config_warnings.png)

## PDF/A-3

Selecting the **[Archive PDF/A-3](../workflows/pdfa_3.mdx)** 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**.

![Attach source file rules for PDF/A-3](/img/config_pdfa3.png)

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](nested-files-attachments.mdx)**.
:::

## PDF/A-1

Selecting the **[Archive PDF/A-1](../workflows/pdfa_1.mdx)** 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 **[Conversion](../workflows/conversion.mdx)** 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*.

![Optimize PDF for speed or size](/img/config_optimize-pdf.png)

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](../configure/configure-stamping.mdx).

| 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 Dossier 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](../configure/configure-stamping.mdx), 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](service-log.mdx) to monitor the status and performance of the service.

You can also use the Conversion Service Configurator to supervise document processsing via **[Health & activity](health-activity.mdx)** and **[Statistics](statistics.mdx)** tabs.

---

## Health & Activity

import useBaseUrl from '@docusaurus/useBaseUrl';

The state and recent activity of the service is monitored by the Health and activity tab of the 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 where 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 are waiting in the queue for being 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 at the right-hand side.

---

## Service log

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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

The location of the standard log files can be configured using the [Service configuration](../configure/configure-win-service.mdx). 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.

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

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

  

    
      
    

  
     
   

   
     
   

 
```

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.
![Support Request tab of the Conversion Service Configurator](/img/config_support_request.png)

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 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.

![Statistics tab of the Conversion Service Configurator](/img/config_statistics.png)

## 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. On the left-hand side, the length of the period can be configured by selecting one of the following time units:
- Day
- Week
- Month

On the right-hand side, the point of time where the period occurred can be selected either by clicking on the calendar icon and choosing it from the calendar dropdown which has appeared or by clicking the arrows.

**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](health-activity.mdx).

`jobs.csv` contains the following columns:  
- `id`: Row number.
- `jobId`: Unique identifier name of the job.
- `worklow`: 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 where 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 are waiting in the queue for being 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 at the right-hand side.

---

## Conversion Service release notes

import useBaseUrl from '@docusaurus/useBaseUrl';

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](./update/README.mdx)**.
:::

---
## Version 6

The following sections provide updates in version 6 of the Conversion Service.

### 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](./configure/configure-stamping.mdx) 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](/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**. For more information, review [Accessibility workflow](./workflows/accessibility.mdx).
- 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 the [Configure profiles using Configurator Web](./configure/configure-profiles-docker.mdx#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](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json) or the [Simple API reference](./api/simple-api/simple-api.info.mdx).

    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](./configure/configure-profiles-docker.mdx#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](./configure/configure-profiles-docker.mdx#configure-profiles-using-configurator-web) section.
- You can now learn how to integrate the Conversion Service using OpenShift with a [Conversion Service on OpenShift](./configure/configure-openshift.mdx) 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.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](./configure/word-track-changes.mdx).
    
    
    
- 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](./configure/configure-win-service.mdx#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](./getting-started/README.mdx) 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](./integrate/connectors/email-connectors.mdx#settings)
    - Watched Mailbox (Exchange Online) [Settings](./integrate/connectors/email-connectors.mdx#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](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-json) and [REST input plain HTTP](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#rest-input-plain-http) connectors. For details how to activate the **HTTPS** communication, review [HTTPS](./configure/configure-win-service.mdx#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](./configure/configure-stamping.mdx) documentation.
- With this release, you can specify which files the Watched Folder connector skips using glob patterns. For more information, review [Configuration options](./integrate/connectors/folder-connectors.mdx#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](../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](./workflows/tiff.mdx) documentation.
- Workflow **Sign**. For more information, see [Sign workflow](./workflows/sign.mdx) 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](../../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 the [Configure output file appearance](/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](./configure/configure-docker-container.mdx).

### 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](/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](./integrate/connectors/rest-connectors/rest-input-connectors.mdx#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](../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](workflows/dossier.mdx)** 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](monitor/statistics.mdx)** 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](monitor/health-activity.mdx)** 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](workflows/conversion.mdx)** 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](workflows/pdfa_3.mdx)** similar to **[Archive PDF/A-2](workflows/pdfa_2.mdx)**, but with support for non-PDF/A attachments.
- Workflow **[Invoice](workflows/invoice.mdx)** 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](integrate/README.mdx)** 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

import DocCardList from '@theme/DocCardList';

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:
        # Configuraiton 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](../configure/configure-docker-container.mdx#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](./windows-server.mdx).
2. [Import updated profiles](../configure/configure-profiles-docker.mdx) 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. Download the installer MSI file from **Licenses & Kits** area of [MyPdfTools](https://my.pdf-tools.com/en/mypdftools/licenses-kits/).
Check the name carefully to identify the latest version, as you may have access to more than one version.    
2. Open the MSI installation package to run the installer.
3. In the installation wizard, click **Next**.
4. Read the license agreement, select the **I accept the Terms** checkbox, and click **Next**.
5. Click **Install**.
6. 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](../configure/office-conversion.mdx).
:::

## 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 `ConversionService-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: `ConversionService-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

import useBaseUrl from '@docusaurus/useBaseUrl';

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 has eight workflows:
- [Conversion](#conversion)
- [Archive PDF/A-2](#archive-pdfa-workflows)
- [Archive PDF/A-3](#archive-pdfa-workflows)
- [Archive PDF/A-1](#archive-pdfa-workflows)
- [Accessibility](#accessibility)
- [Dossier](#dossier)
- [Invoice](#invoice)
- [Archive TIFF](#archive-tiff)
- [Sign](#sign)

You can select **specific configuration settings** for the workflow via **[profiles](../configure/configure-profiles.mdx)**. You can **add [stamps](stamping.mdx)** during the conversion process, and **configure the [metadata](metadata.mdx)** in the resulting output PDF.

## Conversion

The **[Conversion workflow](conversion.mdx)** 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.   

## Archive PDF/A workflows

These workflows are engineered specifically for preparing documents for archiving. They assure conformance according to three specifications:
- **[Archive PDF/A-2](pdfa_2.mdx)**: Default workflow for archiving.
- **[Archive PDF/A-3](pdfa_3.mdx)**: Features and steps are identical to PDF/A-2, but allows you to embed attachments that are not in conformance with PDF/A.
- **[Archive PDF/A-1](pdfa_1.mdx)**: 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 PDF/A workflow chosen.    
For example, if you choose to convert to PDF/A-2 using the Archive 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 PDF/A workflows are identical. All input documents of a job are processed as follows:

  PDF/A workflow steps

  1. Analyze file type
    In a first step, 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.
  2. Validate & 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.
  3. Convert to PDF
    Non-PDF documents (e.g images, Office documents, etc.) are converted to PDF if their format is supported by the Conversion Service.
    Note: The conversion of Office documents requires an additional step which can only be enabled with an appropriate license.
  4. 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.
  5. Apply stamping
    Stamps such as barcodes, text stamps, image stamps or placeholders are added.
  6. Convert to PDF/A
    PDF documents that are not already PDF/A conforming are converted to a high-quality PDF/A.
    Important: The actions performed in this step vary for PDF/A-1 and PDF/A-2 and PDF/A-3.  
  7. Merge / Collect
    The converted documents of a job are merged or collected into a single document, depending on the profile setting. 
  8. Optimize
    The resulting document is compressed and optimized for archiving. This includes several steps: redundant and unnecessary data for archiving 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.
  8. 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.
    

## Accessibility

The **[Accessibility workflow](accessibility.mdx)** is designed to validate PDF documents for compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**.

## Dossier

The **[Dossier workflow](dossier.mdx)** 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.

## Invoice

The **[Invoice workflow](invoice.mdx)** 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.

## Archive TIFF

The **[Archive TIFF](tiff.mdx)** workflow is engineered specifically to prepare documents for archiving in suitable TIFF format.

## Sign

The **[Sign](sign.mdx)** 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**.

---

## Accessibility workflow

This workflow is designed to validate PDF documents for compliance with accessibility standards, including **PDF/UA (ISO 14289)**, **Web Content Accessibility Guidelines 2.1 (WCAG)**, and general **quality guidelines**. The output includes a structured report containing accessibility issues categorized by severity and standard.

This workflow supports the following features:
- PDF/UA validation (ISO 14289-1).
- WCAG 2.1 validation (PDF-specific interpretations).
- General quality checks.
- Customizable filtering of issue severities (for example, ignore or deny warnings).
- JSON and XML report outputs.
- Warning mappings with extensibility based on the [PAC tool](https://pac.pdf-accessibility.org/en).
- Compatible with Docker and Windows deployments.
  
## Supported input file formats

This workflow supports any input in **PDF format**:

- PDF 1.x, PDF 2.0
- PDF/A-1, PDF/A-2, PDF/A-3
- PDF with tags, annotations, or layers.

## Output structure

The result is structured as a hierarchy of **issue nodes**, each of which may contain:

- Severity: `Warning`, `Failure`, `Termination`
- Standard: `PDF/UA`, `WCAG`, `Quality`
- Category and Subcategory (for example *Basic Requirements → Natural Language*)
- The bounding box (for visual issues)
- Page index
- Message

## Output formats

- **JSON**
- **XML**

### 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  |
|----------------------|--------------------|-----------|-------------|
| Document property    | `DOC.PASSWORD`     | **Optional**  | Sets the password for the document. |

---

## Conversion workflow

This workflow is engineered specifically for the conversion of documents to PDF 1.x.
Unlike the Archive 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 workflow supports these 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 Conversion workflow

This workflow supports these 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                          |
| 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](../configure/configure-profiles.mdx). The Conversion 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 can be skipped (removed) during conversion to PDF, such as attachments of emails or PDF documents.
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 can not be converted (e.g. PDF documents containing unrendered XFA, HTML documents) in their orignal 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 its body and attachments. 
Or when converting Word documents, all embedded files can be merged to the converted PDF.

## Job and document options for the Conversion workflow

The Conversion workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- and document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx).
:::

### 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. |

---

## Dossier workflow

import useBaseUrl from '@docusaurus/useBaseUrl';

Learn how to merge multiple PDFs into a single file using the dossier 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 dossier 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 often used in business, legal, academic, and government contexts to present information in a clear, professional, and accessible format.

## Supported file formats for dossier workflow

This workflow takes PDF files as input. To use other document formats, convert them to PDF using a **preprocessing** step in the dossier 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 dossier 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](stamping.mdx) documentation. You can further customize stamps for the dossier workflow using the `DOCUMENT-STAMP-TITLE` option or using a custom option `CUSTOM.OPTION_NAME`. For more information about this customization, review [Placeholders](../configure/configure-stamping.mdx#placeholders) section in stamping documentation.

## Example of the dossier workflow

This example uses the [shell client](../integrate/shell-client.mdx) 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'.
```

## Job and document options for the Dossier workflow

The Dossier workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- or document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |

:::note
You can also set [extended metadata properties](metadata.mdx#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](metadata.mdx). 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](../configure/configure-stamping.mdx#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](../configure/configure-stamping.mdx#placeholders). |

---

## Invoice workflow

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 these features:
- Conversion to PDF/A-3 format
- Additional document attachments
- Office conversion (optional)
- Digital signatures (optional)
  
## Supported file formats for Invoice 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](../integrate/shell-client.mdx) 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'.
```

## Job and document options for the Invoice workflow

The Invoice workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- or document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx#extended-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

import PenIcon from '/img/pen-solid.svg';

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 follwoing 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 PDF/A-1 workflow

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 PDF/A 2](pdfa_2.mdx) 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 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
  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/).
:::

{/* Clarify this section with the full list of features available for the Archive PDF/A-1 workflow

The Archive PDF/A-1 workflow supports these features:
- Conversion to PDF/A-1 format
*/}

## Supported file formats for Archive PDF/A-1 workflow

This workflow supports these 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                          |
| 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 these features can lead to severe visual differences that may render the page's content unreadable.   

The Windows version of the product 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.

### PDF/A-1 specific conversion warnings

The following warnings occur more frequently when converting to PDF/A-1:
- Annotation removed
- Content rasterized
- Layers removed
- Transparency removed
- Visual differences
So the profile's conversion settings for these warnings is particularly important.    
Note: Content rasterized warning appears only in Windows where content rasterization is available; Transparency removed warning only appears in Docker image, where content rasterizaiton is not available.

### Sign

Document signing is currently not implemented.

## Job and document options for the PDF/A-1 workflow

The PDF/A-1 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- and document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx#extended-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 PDF/A-2 workflow

The Archive 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 PDF/A-2 workflow supports these 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 **also valid level B (Basic) documents**. 

The Archive 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, it tries to converts the document to PDF/A-2u. If it is unable to convert to this level, it converts to PDF/A-2b or ends the conversion process in failure.
:::

## Supported file formats for Archive PDF/A-2

The workflow supports these 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                          |
| 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 Archive PDF/A-2 workflow's profile provides detailed configuration options for converting files to the PDF/A-2 standard. All processing steps can be enabled and customized within the [profile configuration](../configure/configure-profiles.mdx).

:::tip 
To view the processing steps in the Archive PDF/A workflows, see [PDF/A workflow steps](./README.mdx#archive-pdfa-workflows).
:::

### Convert mode for child documents (Attachments)

The convert mode defines the documents that are converted (*Convert* option) and are skipped (removed) from the result. When removing documents, a warning (*Skip with Warning* option) or an informational message (*Skip* option) is generated.   

The convert mode can be determined based on the type of the child document, its filename, or the type of its parent document. For example, by default, Microsoft Office files are converted to PDF/A, executables are removed, and other non-convertible documents are removed 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**: the pages of multiple PDF documents can be merged into a single document
- **Attach**: child documents can be attached (embedded) into a PDF document

For example, emails can be converted by creating a PDF collection (Portfolio) of its body 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, but shows a convenient table of the attached documents for easy navigation. The advantage of the Attach collect mode is that all information of the input files and the files' structure can be preserved.     

The **Merge collect mode** creates simple files that can be processed and viewed by all PDF applications. The disadvantage is that only PDF files can be merged. 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).

## Job and document options for the PDF/A-2 workflow

The PDF/A-2 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- and document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx#extended-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 PDF/A-3 workflow

The Archive PDF/A-3 workflow is engineered specifically for preparing documents for archiving. 
The features and processing steps are identical to the ([Archive PDF/A 2](./README.mdx#archive-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 PDF/A-3 workflow supports these 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 PDF/A-3 workflow automatically tries to converts 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 converts 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 PDF/A-3 workflow

The workflow supports these 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                          |
| 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 [PDF/A-2](pdfa_2.mdx#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 [PDF/A-2](pdfa_2.mdx#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](pdfa_2.mdx#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.

## Job and document options for the PDF/A-3 workflow

The PDF/A-3 workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job- and document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx) | `META.AUTHOR` | The author of the document |
| [Metadata](metadata.mdx) | `META.TITLE` | The title of the document |
| [Metadata](metadata.mdx) | `META.SUBJECT` | The subject of the document |
| [Metadata](metadata.mdx) | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx#extended-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 workflow

This workflow is engineered specifically for signing archived documents without removing the existing signatures. 

:::tip
To learn about specific configuration options, review **[Configure signature](../configure/configure-signature/README.mdx)** documentation.
:::

The Sign workflow supports these features:
- Digital Signature (mandatory)

## Supported file formats for Sign 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 PDF/A-2](../workflows/pdfa_2.mdx) workflow to archive PDF into PDF/A format and sign the documents. You can configure digital signatures in the profile configuration of the Archive 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 workflow it's manadatory 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 new signature meanwhile changing the metadata of the document.

:::note
In an appropriate PDF reader you can see the previous signed version with the original metadata.
:::

## Job and document options for the Sign workflow

The sign workflow lets you use [job and document options](../configure/configure-job-and-document-options.mdx) to pass job or document-specific values to be used when processing documents using the workflow.

### 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](metadata.mdx)** | `META.AUTHOR` | The author of the document |
| **[Metadata](metadata.mdx)** | `META.TITLE` | The title of the document |
| **[Metadata](metadata.mdx)** | `META.SUBJECT` | The subject of the document |
| **[Metadata](metadata.mdx)** | `META.KEYWORDS` | Keywords that apply to the document |

:::note
Apart from the standard metadata properties, you can also set [extended metadata properties](metadata.mdx#extended-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](../configure/configure-stamping.mdx)**.
:::

## 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 PDF/A-1](pdfa_1.mdx), [Archive PDF/A-2](pdfa_2.mdx), [Archive PDF/A-3](pdfa_3.mdx) and [Conversion](conversion.mdx) 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 [Dossier](dossier.mdx) workflow, you can choose to stamp of the table of contents or leave it without a stamp.

---

## Archive TIFF workflow

Learn how to automatically convert documents, images, and office files to TIFF format suitable for archiving using the Archive TIFF workflow in the Conversion Service. The Archive TIFF workflow is engineered specifically to prepare documents for archiving.

The Archive TIFF workflow supports these features:
- Single-page or multipage TIFF output
- Office conversion (optional)
- Stamping (optional)

## Supported file formats for Archive TIFF 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                                          |
| Image formats    | JPEG, JPEG200, TIFF, BMP, GIF, JBIG2, PNG, HEIC, HEIF, WebP                          |
| 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.

## Job and document options for the TIFF workflow

Pass job and document-specific values for processing documents using the Archive TIFF workflow. For more information, review [Configure job and document options](../configure/configure-job-and-document-options.mdx).

### 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. |

---

## Digital signature basics

import useBaseUrl from '@docusaurus/useBaseUrl';

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](../../conversion-service/). Review [Configure signature](../../conversion-service/configure/configure-signature/).
- The [Pdftools SDK](../../pdf-tools-sdk/). Review [Sign PDF documents](../../pdf-tools-sdk/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 example](/img/config_signature_certificate_example.png)

## 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.
![Certificate example](/img/config_signature_certificate_example.png)

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](pdf-standards.mdx) 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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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.
- **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.

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:

```

```

:::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.
:::

```
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.
:::

### 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

```

```

:::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.
:::

```

```

:::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.
:::

```
1-5IAXL-C3SJE-040YC-52T0J-CH98P-7KCY7-WLNF0
```

```
0-DHT83-AF2V1-31OG8-5U7FA-KXNBF-YQKS9
```

### 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](/docs/licenses/products/pdf-tools-sdk-license/)
- [Conversion Service license](/docs/licenses/products/conversion-service-license/)
- [PDF Viewer SDK license](/docs/licenses/products/pdf-web-viewer-license/)
- [PDF Toolbox SDK license](/docs/licenses/products/pdf-toolbox-sdk-license/)
- [3-Heights SDK licenses](/docs/licenses/products/3-heights-licenses/)

## 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, contact [Pdftools Technical Support](https://www.pdf-tools.com/helpspot/index.php).

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](/configure/README.mdx).

**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 [My PDF Tools Portal](https://my.pdf-tools.com/en/mypdftools/) 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

import DocCardList from '@theme/DocCardList';
import useBaseUrl from '@docusaurus/useBaseUrl';

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 also 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+)
:::

## License validation modes

You can set up the Pdftools products in several ways to validate the license keys. The Licensing Gateway Service (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](./licensing-service.mdx) 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](./offline-licensing-service.mdx) page.

## 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 |

---

## Containerized mode

Use a Docker image to run the Licensing Gateway Service (LGS) in a containerized environment. This setup allows you to run the LGS in a Docker container with internet access.

:::info Conversion Service in Docker
If you are using the Conversion Service in Docker, use the example file provided in [Configure containers using Docker compose](/docs/conversion-service/configure/configure-docker-container/#configure-containers-using-docker-compose) documentation to enable containerized mode.
:::

## Run the LGS in Docker

Learn how to run the LGS in a Docker container with internet access in the following sections.

### 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/).

### Run LGS in Docker

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/repository/docker/pdftoolsag/license-gateway/general)
1. To start the LGS container with the necessary configurations, use the following Docker command:
    ```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. You can also add multiple license keys. Multiple keys can be separated by a semicolon (`;`), for example:
    ```bash
    -e LICENSE_KEYS="LICENSE_KEY_1;LICENSE_KEY_2"
    ```
    - Replace `LICENSE_KEY_1;LICENSE_KEY_2` with your license keys. You can use one or more license keys. If you use more, seperate them with semicolons `;`.

:::note
This container requires an active internet connection to operate correctly, ensuring that license data is continuously synchronized. During graceful shutdown, an internet connection is also essential to avoid data inconsistencies and prevent the licenses from becoming blocked.
:::

#### Port mapping

The LGS is, by default, running and accessible 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.
    - If you wish to change the host port, update the configuration in the product or CLI 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
```

## 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 the maximum number of instances is exceeded, the license becomes blocked. To prevent this, the LGS automatically unregisters or deactivates the LGS from the pool of LGSs 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 functions correctly, always gracefully shut down the container:

```bash
docker stop CONTAINER_ID
```

If the container cannot connect to the internet during shutdown, it may fail to transfer data properly, potentially blocking the licenses. In such cases, please contact Pdftools support to resolve the issue.

---

## Connected mode

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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 let's you use Pdftools software offline for at least three months. For more details, review [Full offline mode](./offline-licensing-service.mdx).
:::

:::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 the [Licensing Gateway Service](../products/conversion-service-license.mdx#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.

1. Download the LicensingGatewayService.msi package.
1. Run the installer.

The installer copies the required binary files, sets up the port and environment variables, and creates and runs a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.

1. Download the licgwy_amd64.snap package.
1. Run the installer with the following command:
    ```bash
    snap install licgwy_amd64.snap --classic --dangerous
    ```

The installer copies the required files, sets up the port and environment variables, and creates and runs a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.

## Configure the LGS

To configure the LGS:

1. Locate the LGS configuration file `appsettings.json`:

    
    
    For Windows, the file is in the installation folder, for example:

    ```
    C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
    ```
    
    
    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](/docs/support) page.
:::

## 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 LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key first so you can activate it again in 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
licgwy add LICENSE_KEY_VALUE
```
Replace `LICENSE_KEY_VALUE` with your license key.

:::info
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.
:::

:::caution
Use a license key only on **one machine or one proxy service**.
If you want to reuse a license key installed on another machine, return the license key first before adding it to the new machine. Review [Return a license](#return-a-license) for more information.
:::

### Check licenses and the service status

To view all license keys added to the system, use the following command:

```shell
licgwy list
```

To view the connection status between the LGS and the Pdftools Licensing Service, use the following command:

```shell
licgwy status
```

### Synchronize licenses

To establish an active connection between the LGS and the Pdftools Licensing Server manually, use the command:

```shell
licgwy 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
licgwy 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
licgwy remove-all
```

### LGS CLI commands

To access a full list of available commands, use the ` licgwy help` command.

| Command                                       | Description                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `licgwy help`                                 | Get instructions on how to use the CLI with a full list of commands.           |
| `licgwy version`                              | Get the LGS version number.                                                    |
| `licgwy add LICENSE_KEY_VALUE`                | Add a new license key                                                          |
| `licgwy remove LICENSE_KEY_VALUE`             | Remove a license key                                                           |
| `licgwy remove-all`                           | Remove all license keys                                                        |
| `licgwy status`                               | Check the licensing service status.                                            |
| `licgwy list`                                 | Get information about added license keys and for how long they are valid.      |
| `licgwy sync`                                 | Connect to Pdftools Licensing Server on demand (refreshes the time on all borrowed licenses)   |

---

## Full offline mode

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Use the Pdftools software fully offline with valid license keys for at least three months or more, depending on the type of your license. Your local network can stay without an internet connection, and the license keys are validated for a set period of time.

## Before you start

Ensure your license key supports the full offline mode. Whether you can enable the offline mode depends on the order form and quote you accepted from Pdftools. If you require an upgrade to get this feature, reach out through the [Contact form](https://www.pdf-tools.com/contact/).

## Install the LGS

Install the LGS to enable 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 more about implementation of the [Licensing Gateway Service](../products/conversion-service-license.mdx#licensing-gateway-service) in the Conversion Service licensing documentation. Skip to [Configure the LGS for offline use](#configure-the-lgs-for-offline-use) if you installed the Conversion Service on a Windows Server machine. 
:::

:::note
Ensure you install the LGS on an offline machine in full offline mode.
However, in the connected mode, you need to install the LGS on a computer that is connected to the internet.
:::

1. Download the LicensingGatewayService.msi package.
1. Run the installer.

The installer copies the required binary files, sets up the port and environment variables, and creates and runs a Windows service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.

1. Download the licgwy_amd64.snap package.
1. Run the installer with the following command:
    ```bash
    snap install licgwy_amd64.snap --classic --dangerous
    ```

The installer copies the required files, sets up the port and environment variables, and creates and runs a service that acts as an agent to regularly synchronize the LGS with the Pdftools Licensing Server.

## Configure the LGS for offline use

To configure the LGS:

1. Locate the LGS configuration file `appsettings.json`:

    
    
    For Windows, the file is in the instalation folder, for example:

    ```
    C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
    ```
    
    
    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. Enable offline mode in LGS. Update the configuration file so that `IsOfflineMode` property is set to `true`.

    Example configuration file after update:
    ```json
    {
      "LicensingServicePortNumber": 9999,
      "LogFilePath": "C:/logs/pdftls/log.txt",
      "LogRetentionDays": 7,
      "IsOfflineMode": true
    }
    ```

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 are kept.
1. Restart the service after modifying the `appsettings.json` file for the changes to take effect.

## Install the Licensing Gateway Activator

To start using the Licensing Gateway Activator (LGA), download and install the package on a machine in your network that is connected to the internet.

1. Download the LicensingGatewayActivator.msi package.
1. Run the installer.

The installer copies the required binary files and sets up environment variables, so that you can use LGA CLI.

1. Download the licgwyactivator_amd64.snap package.
1. Run the installer with the following command:
    ```bash
    snap install licgwyactivator_amd64.snap --classic --dangerous
    ```

## Offline license configuration

The following sections teach you how to manage your license keys offline using the LGS CLI and LGA CLI tools. Perform each step accurately to maintain the integrity of the licensing process. If you encounter any issues, please contact Pdftools support.

### Prerequisites

To use the license keys offline, fulfill the following prerequisites:
-	The **Licensing Gateway Service CLI** (`licgwy`) is installed on a machine that is **not** connected to the internet (**offline machine**).
-	The **Licensing Gateway Activator CLI** (`licgwyactivator`) is installed on the machine that **is** connected to the internet (**online machine**).

### Activate license key offline

Follow these steps to activate or extend a license key in the offline mode:

1. On the offline machine with installed **Licensing Gateway Service**, run the following command to generate a license request token:
    ```bash
    licgwy export-activation LICENSE_KEY_VALUE
    ```
    - Replace `LICENSE_KEY_VALUE` with your license key.

1. On the online machine with installed **Licensing Gateway Activator**, run the following command to generate a license activation token:
    ```bash
    licgwyactivator activate LICENSE_REQUEST_TOKEN
    ```
    - Replace `LICENSE_REQUEST_TOKEN` with the token from the previous step.

1. On the offline machine, run the following command to activate or extend the license key:
    ```bash
    licgwy import-activation LICENSE_ACTIVATION_TOKEN
    ```
    - Replace `LICENSE_ACTIVATION_TOKEN` with your license activation token from the previous step.

The license is now activated or extended and ready for use.

:::note
When you activate a license key in LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key first so you can activate it again in LGS.
:::

### Deactivate license key offline

**Why deactivate a license key?** If a machine with a license key activated in an LGS becomes inaccessible, the license key will be blocked and unusable. Unfortunately, you won't be able to activate or deactivate the blocked license key and move it to another machine. This often happens with discontinued servers or removed virtual machines where our customers did not deactivate their license key in LGS before removing the machine itself.

:::info
If your license key became blocked, as described in the previous paragraph, contact Pdftools support to unblock the license key. Review the [Support](/docs/support) page.
:::

If you want to remove a machine where you have activated license keys in LGS:
1. Deactivate the license key.
1. Remove the machine.
1. Activate the license key on another machine with LGS.

Follow these steps to deactivate a license key in the offline mode:

1. On the offline machine with installed **LGS**, run the following command to generate a license request token and locally deactivate the license key:
    ```bash
    licgwy export-deactivation LICENSE_KEY_VALUE
    ```
    - Replace `LICENSE_KEY_VALUE` with your license key.
    - You cannot generate a new activation request token for the same license key until you complete all deactivation steps.

1. On the online machine with installed **Licensing Gateway Activator**, run the following command to generate a license deactivation token:
    ```bash
    licgwyactivator deactivate LICENSE_REQUEST_TOKEN
    ```
    - Replace `LICENSE_REQUEST_TOKEN` with the token from the previous step.

1. On the offline machine, run the following command to activate or extend the license key:
    ```bash
    licgwy import-deactivation LICENSE_DEACTIVATION_TOKEN
    ```
    - Replace `LICENSE_DEACTIVATION_TOKEN` with your license activation token from the previous step.

The license is now completely removed from the system. If necessary, you can generate a new activation request token for this license key.

## References

The following sections list the most important LGS and Licensing Gateway Activator commands in the fully offline configuration.

### LGS CLI commands

The LGS includes a command-line interface (CLI) utility for managing licenses associated with your Pdftools products.

To access a full list of available commands, use the `licgwy help` command.

| Command                                       | Description                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `licgwy help`                                 | Get instructions on how to use the CLI with a full list of commands.           |
| `licgwy version`                              | Get the LGS version number.                                                    |
| `licgwy export-activation LICENSE_KEY_VALUE`  | Export an activation request.                                                  |
| `licgwy import-activation LICENSE_ACTIVATION_TOKEN` | Import an activation response.                                                 |
| `licgwy export-deactivation LICENSE_KEY_VALUE` | Export a deactivation request.                                                 |
| `licgwy import-deactivation LICENSE_DEACTIVATION_TOKEN` | Import a deactivation response.                                                |
| `licgwy status`                               | Check the licensing service status.                                            |
| `licgwy list`                                 | Get information about added license keys and for how long they are valid.      |

### Licensing Gateway Activator CLI commands

The Licensing Gateway Activator is a command-line interface that you can use to get activation or deactivation tokens for your offline license keys.

To access a full list of available commands, use the `licgwy help` command.

| Command                       | Description                                                                                    |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| `licgwyactivator help`                 | Get instructions on how to use the CLI with a full list of commands.                           |
| `licgwyactivator version`              | Get the licensing gateway activator version number.                                            |
| `licgwyactivator activate LICENSE_REQUEST_TOKEN`     | Activate an offline token.                                                                     |
| `licgwyactivator deactivate LICENSE_REQUEST_TOKEN`   | Deactivate an offline token.                                                                   |

---

## Configure SSL

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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](licensing-service.mdx#configure-the-lgs) section.
:::

## SSL configuration

To enable SSL compatibility with LGS, follow these steps depending on your operating system:

    
        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"
           ```
    
    
        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
           ```
    
    
        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"
```

---

## 3-Heights SDK product licensing

# 3-Heights SDK 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).

---

## Conversion Service licensing

import Copy from '/img/copy.svg';
import useBaseUrl from '@docusaurus/useBaseUrl';
import GetTrialLicense from '/src/modules/procedure/proc_cs-trial-license.mdx';
import RequestFullLicense from '/src/modules/procedure/proc_cs-full-license.mdx';

Learn how to activate and configure license keys for the 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](../README.mdx).

## Find the Conversion Service license key

:::note Customers before 2024
If you were a customer of Pdftools before November 2024, your license keys can still be in the legacy customer portal. Review [Customers before November 2024: Find the Conversion Service license key](#customers-before-november-2024-find-the-conversion-service-license-key) for more information.
:::

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 the **Copy **.
    
    
    

### Customers before November 2024: Find the Conversion Service license key

To find and copy a license key:

1. Log in to [My PDF Tools Portal](https://my.pdf-tools.com/en/mypdftools/).
2. Click [Licenses & Kits](https://my.pdf-tools.com/en/mypdftools/licenses-kits/).
4. Click **Conversion Service**.
5. In the **License** section, click the **LICENSE** button to reveal the license key, and then click **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 the **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 the **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](../../../conversion-service/configure/configure-docker-container/#manage-license-keys) documentation.
- For Docker Compose containers, review [Configure containers using Docker Compose](../../../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                                                               |

### Dossier page credits

:::info
The [Dossier workflow](../../../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:

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.

If you are using the legacy [Customer portal](https://my.pdf-tools.com/en/mypdftools/licenses-kits/), contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get information about the remaining page credit count.

## 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.

![Licensing Gateway Service configuration with a single machine](/img/license-conv-single-system.png)

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, see the [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, see the [Legacy core-based license key](#legacy-core-based-license-key) section.
:::

![Multiple Systems](/img/license-conv-multiple-systems.png)

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](../../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.

    ![License tab in the Configurator](/img/license-conv.png)

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](/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](/docs/conversion-service/getting-started/docker/#configure-and-export-a-profile) section.
:::

## 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

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 the [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.

---

## PDF Toolbox SDK licensing

# PDF Toolbox SDK licensing

License for this product is managed using the License Manager. For more licensing related information, see the [Technical Note: License Keys](https://www.pdf-tools.com/public/downloads/manuals/TechNoteLicenseKeys.pdf).

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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

Learn how to manage the Pdftools SDK license keys. The information on this page applies to legacy and page-based licenses. The Pdftools SDK also includes the Toolbox add-on that can be used with the same license key.

## Request trial or full license

You can use the Pdftools SDK and the SDK Shell Tool without a license key with watermarked results. To get a full license and remove the watermarks, or to evaluate the Toolbox add-on:

1. Reach out to the sales team through the [Contact page](https://www.pdf-tools.com/contact/) and mark the Pdftools SDK as the product of your interest for a trial license.

## Find the license key

To find and copy a license key:

1. Log in to [My PDF Tools Portal](https://my.pdf-tools.com/en/mypdftools/).
2. Click [Licenses & Kits](https://my.pdf-tools.com/en/mypdftools/licenses-kits/).
4. Click **Pdftools SDK**.
5. In the **License** section, click the **LICENSE** button to reveal the license key, and then click **COPY**.

Use the license key in the same format as you copied it. Include the less-than (``) signs.

## Trial license

## Licensing credit count

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 Toolbox-add-on for specific operations:

| Operation                  | Page credits used |
|----------------------------|-------------------|
| Annotate                   | 1                 |
| Add or remove content      | 1                 |
| Add and fill form fields   | 1                 |
| Archive PDF/A-2            | 2                 |
| Archive PDF/A-3            | 2                 |
| Archive PDF/A-1            | 2                 |
| Redact                     | 1                 |
| Compress and optimize      | 1                 |
| Convert                    | 1                 |
| Create layout for printing | 1                 |
| Extract                    | 1                 |
| Embed e-invoice            | 1                 |
| Generate PDFs              | 1                 |
| Manage metadata            | 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. 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](../configure/README.mdx). The SDK connects to the Pdftools Licensing Service to provide information on usage and retrieve new licensing parameters after processing a document.

The Pdftools Licensing Service collects the following statistics and information:

- License number
- 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](../configure/README.mdx).

## Activate the Pdftools SDK license

Learn how to activate a license key for the Pdftools SDK. Review the appropriate link for your programming language: 

- [Initialize the SDK C](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-c#optional-initialize-the-sdk)
- [Initialize the SDK Java](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-java#optional-initialize-the-sdk)
- [Initialize the SDK .NET](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-dotnet#optional-initialize-the-sdk)
- [Initialize the SDK Python](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python#optional-initialize-the-sdk)
- [Initialize the SDK Other languages and frameworks](/docs/pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-other-languages#use-the-pdftools-sdk-with-go)

## Activate the Toolbox add-on license

Learn how to activate a license key for the Toolbox add-on. Review the appropriate link for your programming language: 

- [Initialize the SDK C](/docs/pdf-tools-sdk/getting-started/toolbox/toolbox-c#initialize-the-sdk)
- [Initialize the SDK Java](/docs/pdf-tools-sdk/getting-started/toolbox/toolbox-java#initialize-the-sdk)
- [Initialize the SDK .NET](/docs/pdf-tools-sdk/getting-started/toolbox/toolbox-dotnet#initialize-the-sdk)

## Use Pdftools SDK Shell Tool license

Learn how to use the Pdftools SDK Shell Tool license key:

- [Use of license key](/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 connect to the Pdftools Licensing Service directly. 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](/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`.

```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$");
```

```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$");
```

:::note
More information about the `LicensingService` property is available in the SDK documentation for [.NET](https://api-reference.pdf-tools.com/pdfsdk/1.3/dotnet/html/P_PdfTools_Sdk_LicensingService.htm) and [Java](https://api-reference.pdf-tools.com/pdfsdk/1.3/javadoc/com/pdftools/Sdk.html#setLicensingService(java.net.URI)).
:::

## Check the license status

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 to be processed, based on the license agreement.
- `Overconsumption`: The number of pages available to be processed, before the SDK stops functioning.

If the `RemainingPages` value reaches zero, the Pdftools SDK provides a limited number of `Overconsumption` pages. The `Overconsumption` pages give you time 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 SDK documentation for [.NET](https://api-reference.pdf-tools.com/pdfsdk/latest/dotnet/html/P_PdfTools_Sdk_LicenseInfoSnapshot.htm) and [Java](https://api-reference.pdf-tools.com/pdfsdk/latest/javadoc/com/pdftools/Sdk.html#getLicenseInfoSnapshot()).
:::

## 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-based 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-based 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 [Using a proxy server](/docs/pdf-tools-sdk/sign-and-secure/sign/configure-digital-signing/#using-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 [Activate the Pdftools SDK license](#activate-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?utm_source=chatgpt.com) in the .NET API documentation.
- Toolbox add-on currently doesn't support proxy configuration.
:::

---

## PDF Viewer SDK licensing

import ViewerPricing from '/src/modules/reference/ref_viewer-pricing-table.mdx';

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.

## Version 5

### License overview

### 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](/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/@pdf-tools/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](/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:

```

```

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.

---

## PDF Toolbox SDK

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The PDF Toolbox SDK lets you create, extract, assemble, and modify PDF documents.

:::tip
For an overview of the features of the PDF Toolbox SDK, see **[key features](overview/README.mdx#key-features)**.
:::

:::info
The PDF Toolbox SDK features and functionality are also included in the Toolbox add-on for the Pdftools SDK. The Toolbox add-on is recommended for new customers. For more information, review [Pdftools SDK](/docs/pdf-tools-sdk/).
:::

## Interfaces

PDF Toolbox SDK is available for multiple desktop/server environments and programming languages:

**Languages**

- [.NET Framework](sdk-dotnet.mdx)
- [.NET Core](sdk-dotnet.mdx)
- [C/C++](sdk-c.mdx)
- [Java](sdk-java.mdx)

| Version                                                 | Bit version |
| ------------------------------------------------------- | ----------- |
| Windows Client 7+                                       | x86 and x64 |
| Windows Server 2008, 2008 R2, 2012, 2012 R2, 2016, 2019 | x86 and x64 |

| Version      | Bit version   |
| ------------ | ------------- |
| macOS 10.10+ | x64 and arm64 |

| Version           | Bit version |
| ----------------- | ----------- |
| Red Hat           | x64         |
| CentOS 9+         | x64         |
| Ubuntu 22.04+     | x64         |
| Oracle Linux 8+   | x64         |
| Fedora 29+        | x64         |
| Debian 10+        | x64         |
| Linux kernel 2.6+ | x64         |
| GCC Toolset 4.8+  | x64         |
| glibc 2.34+       | x64         |

---

## Formats & conformance

The PDF Toolkit SDK supports these formats:

| PDF                         | Image    | Font           |
| --------------------------- | -------- | -------------- |
| PDF 1.x (PDF 1.0 - PDF 1.7) | BMP      | Type1          |
| PDF 2.0                     | DIB      | TrueType       |
| PDF/A-1                     | JPEG     | OpenType       |
| PDF/A-2                     | JPEG2000 | OpenType (CFF) |
| PDF/A-3                     | JBIG2    |                |
| FDF                         | PNG      |                |
|                             | GIF      |                |
|                             | TIFF     |                |

It generates PDF files that conform to these standards:

- ISO 32000-1 (PDF 1.7)
- ISO 32000-2 (PDF 2.0)
- ISO 19005-1 (PDF/A-1)
- ISO 19005-2 (PDF/A-2)
- ISO 19005-3 (PDF/A-3)

:::note
This product is the successor of the 3-Heights® PDF Toolbox API. For the task of migrating existing projects from
3-Heights®, see the [migration guide](migration-guide/README.mdx).
:::

## PDF Toolbox SDK and Toolbox add-on

**PDF Toolbox SDK** is a standalone product that is maintained under LTS support. The **Toolbox add-on** is an add-on for the **Pdftools SDK** that lets you implement the same functionality as the **PDF Toolbox SDK** and receive new feature updates. With the **Toolbox add-on** you can use the same license key as the **Pdftools SDK**. For more information, review [Getting started with the Toolbox add-on](../pdf-tools-sdk/getting-started/toolbox/) and [Toolbox Code samples](../pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/).

---

## Code samples

Here you'll find some samples to get you started with the PDF Toolbox SDK.

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## Install the PDF Toolbox SDK

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Depending on the language you want to use, the PDF Toolbox SDK can be installed in various ways.

**Steps to install the PDF Toolbox SDK:**

1. [Install the package](#install-the-package).
2. [Set a color profile](#install-color-profiles).
3. [Install fonts](fonts.mdx).
4. [Set the license key](register-license-key.mdx).
5. Locate the [temp files directory](#temp-files-directory) and [cache directory](#cache-directory).

## Install the package

Select the interface language of the library for specific instructions on how to install the package.

## NuGet package

NuGet is a package manager that facilitates the integration of libraries for software development in .NET.
The NuGet package for the PDF Toolbox SDK contains all the libraries needed, managed and native, for all supported operating systems.

You can get the NuGet package `PdfTools.PdfToolbox.4.0.1.nupkg` directly from [https://www.nuget.org/](https://www.nuget.org/) or download it from the Pdftools website.
In Microsoft Visual Studio, this is the default location for downloading packages.

The `PdfTools.PdfToolbox.4.0.1.nupkg` package contains .NET libraries with version .NET Standard 2.0, and native libraries for Windows, macOS and Linux.

The required native libraries are loaded automatically. All project platforms are supported, including `AnyCPU`.

To use the SDK, you need to [register your license key](register-license-key.mdx).

:::note
This NuGet package is only supported on a subset of the operating systems supported by .NET Core. See [operating systems](../README.mdx#interfaces)
:::

:::info
The PDF Toolbox SDK requires **Java version 7 or higher**.  
For more information on compilation and execution with the Java interface, see [PDF Toolbox SDK for Java](../sdk-java.mdx).
:::

## ZIP package

You install the PDF Toolbox SDK for Java using a ZIP archive.

:::caution
Ensure that your system matches one of the supported [operating systems](../README.mdx#interfaces).
:::

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `C:\Program Files\PDF Tools AG\`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lib`        | Contains the runtime executable binaries and runtime import libraries:  `win-x86\PdfToolbox.dll` and `win-x86\PdfToolbox.lib` for 32-bit Windows  `win-x64\PdfToolbox.dll` and `win-x64\PdfToolbox.lib` for 64-bit Windows |
| `doc`        | Contains documentation                                                                                                                                                                                                               |
| `jar`        | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`.                                                                                                                                                               |

3. You may want to add the `lib\win-x64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
4. To use the SDK, you need to [register your license key](register-license-key.mdx).

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g, `/opt/pdftools.com/`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `lib`        | Contains the runtime executable binaries:  `linux-x64/libPdfToolbox.so` for 64-bit Linux |
| `doc`        | Contains documentation                                                                        |
| `jar`        | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`.                        |

3. You may want to create a link to the shared library from one of the standard library directories. For example,

```
ln -s /opt/pdf-tools.com/lib/linux-x86/libPdfToolbox.so /usr/lib
```

4. To use the SDK, you need to [register your license key](register-license-key.mdx).

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib`        | Contains the runtime executable binaries:  `osx-x64/libPdfToolbox.dylib` for 64-bit (Intel) macOS  `osx-arm64/libPdfToolbox.dylib` for ARM (Apple Silicon) macOS |
| `doc`        | Contains documentation                                                                                                                                                     |
| `jar`        | Contains Java archive file `com.pdf_tools.fourheights.pdftoolbox.jar`.                                                                                                     |

3. The library must have the extension `.jnilib` for use with Java. You may want to create a file link for this purpose. For example,

```
ln libPdfToolbox.dylib libPdfToolbox.jnilib
```

4. To use the SDK, you need to [register your license key](register-license-key.mdx).

The PDF Toolbox SDK for C comes as a ZIP archive.

:::important
Ensure that your system matches one of the supported [operating systems](../README.mdx#interfaces).
:::

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `C:\Program Files\PDF Tools AG\`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lib`        | Contains the runtime executable binaries and runtime import libraries:  `win-x86\PdfToolbox.dll` and `win-x86\PdfToolbox.lib` for 32-bit Windows  `win-x64\PdfToolbox.dll` and `win-x64\PdfToolbox.lib` for 64-bit Windows |
| `include`    | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers.                                                                                                           |

3. You may want to add the `lib\win-x64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.
4. To use the SDK, you need to [register your license key](register-license-key.mdx).

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `lib`        | Contains the runtime executable binaries:  `linux-x64/libPdfToolbox.so` for 64-bit Linux                              |
| `include`    | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers. |

3. You may want to 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/libPdfToolbox.so /usr/lib
```

4. To use the SDK, you need to [register your license key](register-license-key.mdx).

1. Log in to your account on Pdftools website and download the ZIP archive and the license key for the PDF Toolbox SDK.
2. Unzip the archive to a local directory, e.g. `/opt/pdftools.com/`.  
   This creates the following subdirectories:

| Subdirectory | Description                                                                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib`        | Contains the runtime executable binaries:  `osx-x64/libPdfToolbox.dylib` for 64-bit (Intel) macOS  `osx-arm64/libPdfToolbox.dylib` for ARM (Apple Silicon) macOS |
| `include`    | Contains the header files to include in your C/C++ project. The main header `PdfToolbox.h` includes all the other headers.                                                 |

3. You may want to 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/libPdfToolbox.dylib /usr/lib
```

4. To use the SDK, you need to [register your license key](register-license-key.mdx).

## Install color profiles

Most systems have pre­installed color profiles available. If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the PDF Toolbox SDK.

Color profiles can also be downloaded from the following websites:

- http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip
- http://www.color.org/srgbprofiles.html
- https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html

For device RGB colors, a color profile `sRGB Color Space Profile.icm`, and for device CMYK, a profile `USWebCoatedSWOP.icc` are searched for in the following directories (recursively, in the order specified).

To install a color profile, download and copy the profile to the corresponding folder:

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

1. `$PDF_ICC_PATH` if the environment variable is defined
2. The current working directory

1. `$PDF_ICC_PATH` if the environment variable is defined
2. The current working directory

## Temp files directory

This directory for temporary files is used for data specific to one instance of a program. The data is not shared between different invocations and deleted after termination of the program.

The directory depends on the operating system. The product checks for the existence of environment variables in the following order and uses the first path found:

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

1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.

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 is persisted and shared between different invocations of a program. The actual caches are created in subdirectories. The content of this directory can safely be deleted to clean all caches.

This directory should be writable by the application. Otherwise, caches cannot be created or updated and performance degrades significantly.

- If the user has a profile: `%LOCAL_APPDATA%\PDF Tools AG\Caches`
- If the user has no profile: `\PDF Tools AG\Caches`

- If the user has a home directory: `~/.pdf-tools/Caches`
- If the user has no home directory: `/pdf-tools/Caches` where `` refers to the [directory for temporary files](#temp-files-directory)

- If the user has a home directory: `~/.pdf-tools/Caches`
- If the user has no home directory: `/pdf-tools/Caches` where `` refers to the [directory for temporary files](#temp-files-directory)

---

## Install fonts for the SDK

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

When text is created by the PDF Toolbox SDK, all fonts from the [Font directories](#font-directories) can be used.

## Install system fonts

On Windows, macOS, and Linux, when a font is installed, it is by default installed only for a particular user. It is important to either install
fonts for all users, or make sure the PDF Toolbox SDK is run under that user and the user profile is loaded.

For Linux, it is recommended you use Font Manager to install all system fonts.

## Font directories

The location of the font directories depends on the operating system. Font directories are traversed recursively in the order as specified below.

If two fonts with the same name are found, the latter one takes precedence, i.e. user fonts always take precedence over system fonts.

1. `%SystemRoot%\Fonts`
2. User fonts listed in the registry key `\HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Fonts`. This includes user-­specific fonts from `C:\Users\\AppData\Local\Microsoft\Windows\Fonts` and app specific fonts from `C:\Program Files\WindowsApps`
3. `Fonts` directory, which must be a direct subdirectory of where `PdfToolboxAPI.dll` resides.

1. `/usr/share/fonts`
2. `/usr/local/share/fonts`
3. `~/.fonts`
4. `$PDFFONTDIR or /usr/lib/X11/fonts/Type1`

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

## 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 PDF Toolbox 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](./README.mdx#cache-directory).

---

## Register license key

To obtain an evaluation license key or full license key, contact the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/).

Set the license key by using the `Sdk.Initialize` method before calling the library.

:::note
The PDF Toolbox SDK and the Pdftools SDK differ in how they provide free or trial license keys (also called evaluation license keys in Pdftools).

- PDF Toolbox SDK: 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: You can try the Pdftools SDK without a license key with watermarked output files. 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. No evaluation license key is necessary to try the Pdftools SDK.
:::

---

## C interface changes for PDF Toolbox SDK

There are several changes in naming and behavior in the C interface to bear in mind when migrating from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

## Prefixes

The name of all interface elements such as declared structs and functions, starts with a prefix. In 3-Heights® PDF Toolbox API PDF Toolbox API, all interface elements have the same prefix. The PDF Toolbox SDK introduces the following new prefixes:

| Prefix           | Area of usage               |
| ---------------- | --------------------------- |
| `Ptx`            | Base prefix                 |
| `PtxGeom`        | Geometric related           |
| `PtxGeomReal`    | For floating point numbers  |
| `PtxGeomInteger` | For integer numbers         |
| `PtxPdf`         | General PDF related         |
| `PtxPdfAnnots`   | Annotation related          |
| `PtxPdfContent`  | Page content related        |
| `PtxPdfForms`    | Form field related          |
| `PtxPdfNav`      | Document navigation related |

## The Sdk functions

### License keys and product version
In 3-Heights® PDF Toolbox API, `PdfSetLicenseKey` and `PdfGetProductVersion` functions allows setting a license key and querying the version of the API.

In the, this functionality has been moved to the class `TPtx_Sdk`. Specifically:

- `Ptx_Sdk_Initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Ptx_Sdk_GetVersion` gets the API’s version number as a string.

### The PDF Producer entry
In 3-Heights® PDF Toolbox API, when creating a PDF, the `TPdfMetadata` object sets the PDF’s “Producer” entry via the related function `PdfMetadataSetProducer`.

In the PDF Toolbox SDK, the class `TPtxPdf_Metadata` has no related function `PtxPdf_Metadata_SetProducer`. Instead, the “Producer” entry for all output PDFs is preconfigured as a string consisting of two parts:

1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a licensef rom Pdftools.
2. The second part (the “suffix” part) is configured when calling `Ptx_Sdk_Initialize` as an argument. It is recommended to use the suffix solely for version information.

The assembled “Producer” entry can be obtained after calling `Ptx_Sdk_Initialize` using the related function `Ptx_Sdk_GetProducerFullName`.

## Closing and releasing

In 3-Heights® PDF Toolbox API, all native objects support a “closing” operation by means of the `PdfClose` function.

In the PDF Toolbox SDK, only the following classes support closing by means of a dedicated function:

- `TPtxPdf_Document`
- `TPtxPdfContent_ContentGenerator`
- `TPtxPdfContent_TextGenerator`

Specifically, the objects on which these classes operate are not fully constructed until closing. For all other objects, associated resources can be freed by calling `Ptx_Release`. Using an object after releasing results in undefined behavior.

## Elements changed to class or struct

The following 3-Heights® PDF Toolbox API structs have changed to opaque classes in the PDF Toolbox SDK:

- `TPdfEncryptionParams` → `TPtxPdf_Encryption`
- `TPdfFillParams` → `TPtxPdfContent_Fill`
- `TPdfStrokeParams` → `TPtxPdfContent_Stroke`
- `TPdfTransparencyParams` → `TPtxPdfContent_Transparency`

Hence, such objects cannot be allocated on the stack. The related initialization functions `...Initialize` have been removed. In turn, they receive allocation functions `...New`.

As a consequence, the following functions now directly return a pointer to the object:

- `PtxPdfContent_Paint_GetTransparency`
- `PtxPdfContent_PathElement_GetFill`
- `PtxPdfContent_PathElement_GetStroke`
- `PtxPdfContent_TextFragment_GetFill`
- `PtxPdfContent_TextFragment_GetStroke`

Conversely, the following 3-Heights® PDF Toolbox API class has changed to an explicitly defined struct in the PDF Toolbox SDK:

- `TPdfTransformation` → `TPtxGeomReal_AffineTransform`

Hence, such objects can be allocated on the stack. See also [Affine transform objects should be initialized](#affine-transform-objects-should-be-initialized).

As a consequence, the following functions take a last argument `TPtxGeomReal_AffineTransform`\*, a pointer to an already allocated struct:

- `PtxPdfContent_TextFragment_GetTransform`
- `PtxPdfContent_ContentElement_GetTransform`

## Renaming

Some interface elements have been renamed in addition to the introduction of new Prefixes. The following principles apply:

- Interface elements that include abbreviations are now written consistently in Pascal case, e.g. `RGB → Rgb`, except for two-letter abbreviations, which are written as two capital letters, e.g. `IO`.
- Some abbreviations have been changed to full words, e.g. `Char → Character`.
- Some words that are repeated in the introduced prefix namespace have been dropped, e.g.`TPdfAnnotationPopup` → `TPtxPdfAnnots_Popup`.
- List appending function are renamed: `...Append→...Add`.
- Improved clarity, brevity, jargon, and technical correctness.

## Affine transform objects should be initialized

In 3-Heights® PDF Toolbox API, `TPdfTransformation` is a “class”. In the PDF Toolbox SDK, this element has been renamed to `TPtxGeomReal_AffineTransformation`, and its type has changed to “struct”.
See [Elements changed to class or struct](#elements-changed-to-class-or-struct).

Specifically, default constructed `TPtxGeomReal_AffineTransform` objects are not valid. (A matrix with all values0is singular.) Default constructed `TPtxGeomReal_AffineTransform` objects should always be initialized with `PtxGeomReal_AffineTransform_GetIdentity`.

For example:

```
TPtxGeomReal_AffineTransform transform;
PtxGeomReal_AffineTransform_GetIdentity(&transform);
```

## Creation and copying methods

In 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by related functions `PdfDocumentCreate...` and copied from an input document to an output document by related functions `PdfDocumentCopy...`, e.g. `PdfDocumentCreatePage`, `PdfDocumentCopyPage`.

In the PDF Toolbox SDK, all these related functions have been moved from the `TPdfDocument` class to the class that is created or copied. For example, related function `PdfDocumentCreatePage` → `PtxPdf_Page_Create`. This affects the following classes:

- `TPdfPage`
- `TPdfImage`
- `TPdfImageMask`
- `TPdfFont`
- `TPdfGroup`
- `TPdfColorSpace`
- `TPdfPaint`
- `TPdfText`
- `TPdfMetadata`
- `TPdfFileReference`
- `TPdfSubForm`
- `TPdfGeneralTextField`
- `TPdfCombTextField`
- `TPdfCheckBoxField`
- `TPdfRadioButtonField`
- `TPdfListBoxField`
- `TPdfComboBoxField`
- `TPdfNamedDestination`
- `TPdfOutlineItem`
- `TPdfAnnotation`
- `TPdfLink`
- `TPdfFileAttachmentAnnotation`
- `TPdfFreeTextAnnotation`
- `TPdfStickyNoteAnnotation`
- `TPdfTextStampAnnotation`
- `TPdfCustomStampAnnotation`
- `TPdfCircleAnnotation`
- `TPdfSquareAnnotation`
- `TPdfLineAnnotation`
- `TPdfPolyLineAnnotation`
- `TPdfPolygonAnnotation`
- `TPdfFreeDrawingAnnotation`
- `TPdfContentElement`
- `TPdfFormFieldNode`

## Constructors

In 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example: `PdfNewFitPageDestination`.

In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with related functions `..._Create` and `..._Copy`.

This affects the following classes:

- `TPdfEmbeddedPdfLink`
- `TPdfFitHeightDestination`
- `TPdfFitPageDestination`
- `TPdfFitRectangleDestination`
- `TPdfFitWidthDestination`
- `TPdfLocationZoomDestination`
- `TPdfWebLink`

In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:

- `TPtxPdf_Encryption`
- `TPtxPdfContent_ContentExtractor`
- `TPtxPdfContent_ContentGenerator`
- `TPtxPdfContent_Fill`
- `TPtxPdfContent_PageCopyOptions`
- `TPtxPdfContent_PathGenerator`
- `TPtxPdfContent_Path`
- `TPtxPdfContent_Stroke`
- `TPtxPdfContent_TextGenerator`
- `TPtxPdfContent_Transparency`
- `TPtxPdfNav_OutlineCopyOptions`

All constructors have been renamed:
`PdfNew‹Type›` → `‹Prefix›_‹Type›_New`

## Unknown PDF conformance

In 3-Heights® PDF Toolbox API, the `TPdfConformance` enumeration has a value `ePdfUnk`. The PDF Toolbox SDK enum `TPtxPdf_Conformance` has no such value.

The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:

- In the related function `PtxPdf_Document_Create`, the type of the second argument has changed from `TPdfConformance` to `TPtxPdf_Conformance`\*, where a `NULL` value has the same meaning as the removed value `ePdfUnk`.
- The related function `PtxPdf_Document_GetConformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with `NUL`L), the conformance the output PDF would have if closed now.

## Copy options

In 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `TPdfCopyOption` enum.

In the PDF Toolbox SDK, this enum has been substituted by new classes:

- `TPtxPdf_PageCopyOptions` Used in related functions `PtxPdf_Page_Copy` and `PtxPdf_Group_CreateFromPage`.
- `TPtxPdfNav_OutlineCopyOptions`
- Used in related function `PtxPdfNav_OutlineItem_Copy`.

Each copying configuration decision is reflected in a class member. Apart from `BOOL for on-off decisions, the following enumerations model possible choices:

- `TPtxPdf_CopyStrategy`
- `TPtxPdf_RemovalStrategy`
- `TPtxPdf_NameConflictResolution`
- `TPtxPdfForms_FormFieldCopyStrategy`
- `TPtxPdfNav_NamedDestinationCopyStrategy`

This clarifies the copying behavior and allows sensible default values.

## Color space classes

**Class hierarchy**  
In 3-Heights® PDF Toolbox API, there is a single class `TPdfColorSpace`, which covers all types of color spaces.

In the PDF Toolbox SDK, there are the following new classes, all extending `TPtxPdfContent_ColorSpace`:

- `TPtxPdfContent_CalibratedGrayColorSpace`
- `TPtxPdfContent_CalibratedRgbColorSpace`
- `TPtxPdfContent_DeviceCmykColorSpace`
- `TPtxPdfContent_DeviceGrayColorSpace`
- `TPtxPdfContent_DeviceRgbColorSpace`
- `TPtxPdfContent_IccBasedColorSpace`
- `TPtxPdfContent_IndexedColorSpace`
- `TPtxPdfContent_LabColorSpace`
- `TPtxPdfContent_NChannelColorSpace`
- `TPtxPdfContent_SeparationColorSpace`

The 3-Heights® PDF Toolbox API color space type“DeviceN”now is subsumed by the more generalTPtxPdfContent_NChannelColorSpace.

**Device color spaces versus process color spaces**  
In 3-Heights® PDF Toolbox API, the related function `PdfDocumentCreateDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.

In the PDF Toolbox SDK, the enumeration `TPdfDeviceColorSpaceType` has been renamed to `TPtxPdfContent_ProcessColorSpaceType`. The struct `TPtxPdfContent_ColorSpace` now has the following related function:

```
TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_CreateProcessColorSpace(TPtxPdf_Document*,
    TPtxPdfContent_DeviceColorSpaceTypeiType)
```

This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.

## Embedded/Associated/Attached files

In 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `TPdfFileAttachmentAnnotation` are jointly listed in the related function `PdfDocumentGetEmbeddedFiles`.

In the PDF Toolbox SDK, embedded files, associated files, and files contained in fileattachment annotations are treated separately. `ATPtxPdf_Document` now has two lists for appending:

- `PtxPdf_Document_GetAssociatedFiles`
- `PtxPdf_Document_GetPlainEmbeddedFiles`

The former related function `PdfDocumentGetEmbeddedFiles` has been renamed to `PtxPdf_Document_GetAllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `TPtxPdfAnnots_FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the “Attachments” pane in the Adobe PDF viewer.

## Annotations

In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:

- `TPdfFreeDrawingAnnotation` → `TPtxPdfAnnots_InkAnnotation`
- `TPdfCircleAnnotation` → `TPtxPdfAnnots_EllipseAnnotation`
- `TPdfSquareAnnotation` → `TPtxPdfAnnots_RectangleAnnotation`

The related functions `PdfRadioButtenFieldGetCanToggleOff` and `PdfRadioButtenFieldSetCanToggleOff` have been removed. In most PDF viewers, there is no support for this feature.

**Class hierarchy**  
In 3-Heights® PDF Toolbox API, `TPdfWidget` and `TPdfLink` extend the base class `TPdfAnnotation`.

In the PDF Toolbox SDK, the classes `TPtxPdfForms_Widget` and `TPtxPdfNav_Link` have been separated from their former base class. Due to this separation:
`ATPtxPdf_Page` now has the following lists:

- `PtxPdf_Page_GetAnnotations`
- `PtxPdf_Page_GetLinks`
- `PtxPdf_Page_GetFormFieldWidgets`

The following related functions of `TPtxPdfAnnots_Annotation` have been replicated for `TPtxPdfForms_Widget` and `TPtxPdfNav_Link`:
`..._GetBoundingBox`
`..._GetHidden`
`..._GetNoPrint`

The intermediate base classes `TPdfPolyDrawingAnnotation` and `TPdfShapeDrawingAnnotation` havebeen removed. All drawing annotations now directly extend the class `TPtxPdfAnnots_DrawingAnnotation`.Those drawing annotations that have a closed path (`TPtxPdfAnnots_PolygonAnnotation`,`TPtxPdfAnnots_EllipseAnnotation`,`TPtxPdfAnnots_RectangleAnnotation`) have related functions `...GetFill` and `...SetFill`.

**Class hierarchy comparison**

| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |

![C class hierarchy comparison diagram](/img/Toolbox_C-class-comparison.png)

## MaxLength in text fields

In 3-Heights® PDF Toolbox API, the error behavior of the related function `PdfTextFieldSetMaxLength` depends on the actual underlying class: `TPdfGeneralTextField` allows `NULL` values, while `TPdfCombTextField` does not.

In the PDF Toolbox SDK, the related functions `PdfTextFieldGetMaxLength` and `PdfTextFieldSetMaxLength` havebeen removed and replicated in the derived classes `TPtxPdfForms_CombTextField` and `TPtxPdfForms_GeneralTextField`, in the latter as a nullable `int`\*.

## Unified paint creation

In 3-Heights® PDF Toolbox API, there exist three related functions for creating a `TPdfPaintobject:
PdfDocumentCreateSolidPaint
PdfDocumentCreateAlphaPaint
PdfDocumentCreateBlendingPaint

In the PDF Toolbox SDK, these related functions have been replaced by a single related functionPtxPdfContent_Paint_Create.See alsoCreation and copying methods.

## Separate inside rule from path

In 3-Heights® PDF Toolbox API, the related function `PdfNewPath` has an argument `TPdfInsideRuleiRule`.
In the PDF Toolbox SDK, this argument is dropped. Instead, the `TPdfInsideRule` now is specified in a new member of `TPtxPdfContent_Fill` when painting the path with `PtxPdfContent_ContentGenerator_PaintPath`, or it is specified in a method argument when clipping with `PtxPdfContent_ContentGenerator_ClipWithPath`.This removes ambiguity and allows a separated treatment of the insiderule for path filling and path clipping.

## Path and text clipping operations

In 3-Heights® PDF Toolbox API, the `TPdfContentGenerator` supports simultaneous clipping and painting operations.

In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:

- The argument `BOOL` `bIntersectClipPath` has been removed from the related function `PdfContentGeneratorPaintPath`.
- The related function `PdfTextGeneratorSetRendering` has been removed (see also [Text generator](#text-generator)), and its argument `BOOL` `bIntersectClipping` has been dropped without a replacement.
- The new class `TPtxPdfContent_ContentGenerator` has two new methods for path and text clipping operations:
  `PtxPdfContent_ContentGenerator_ClipWithPath`
  `PtxPdfContent_ContentGenerator_ClipWithText`

To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.

## Text generator

In the PDF Toolbox SDK, the related function `PdfTextGeneratorSetRendering` has been substituted by two separate related functions:

- Related function `PtxPdfContent_TextGenerator_SetFill`
- Related function `PtxPdfContent_TextGenerator_SetStroke`

## Image size and image mask size

In 3-Heights® PDF Toolbox API, `TPdfImage` and `TPdfImageMask` have related functions `...GetWidth` and `...GetHeight`.

In the PDF Toolbox SDK, these are substituted by related functions `PtxPdfContent_Image_GetSize` and `PtxPdfContent_ImageMask_GetSize`, both of which have the new type `TPtxGeomInt_Size`.

---

## Reference

For all changes in the C interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see **[C Reference](c-reference.mdx)**.

---

## Migrating from 3-Heights® PDF Toolbox API to the PDF Toolbox SDK

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

This guide explains how to migrate from 3-Heights® PDF Toolbox API (version 6.12) to the PDF Toolbox SDK (version 2.2 and higher).

Follow these steps to migrate your project to the PDF Toolbox SDK:

1. Read the [overview](#overview) and [changes for your chosen interface](#changes-to-the-interface), and adapt your project accordingly.
2. Use the [source code migration script](use-migration-script.mdx) initiate source code migration. This step can alternatively be done manually with the help of the reference.
3. Refer to [interface changes](#changes-to-the-interface) to update your code to reflect incompatible interface changes and changed functional behavior. The [source code migration script](use-migration-script.mdx) can help you in this step by marking code that needs attention.
4. Run your tests. For many changes, **making the source code compile does not guarantee the same behavior**. As an additional source of correct usage of the PDF Toolbox SDK, [source code samples](../code-samples/README.mdx) are available.

---

## Overview

Despite a general similarity in packaging, platform support, programming language bindings, and API, there are significant differences between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK.

## Packaging

The 3-Heights® PDF Toolbox API comes as four different ZIP archives `PdfToolbox-API-‹version›-‹platform›.[zip|tar.gz]`, one for each platform.
The PDF Toolbox SDK comes as a single ZIP archive `PdfToolbox_C-‹version›.zip`.

The 3-Heights® PDF Toolbox API comes as a NuGet package, which targets

- .NET Framework 2.0 and higher
- .NET Standard 1.1
- .NET Standard 2.0

The PDF Toolbox SDK comes as a NuGet package, which targets

- .NET Standard 2.0

All NuGet packages are hosted on [https://www.nuget.org](https://www.nuget.org).

| 3-Heights® PDF Toolbox API                                                                                                                                              | PDF Toolbox SDK                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3-Heights® PDF Toolbox JAR file `PdfToolboxAPI.jar`                                                                                                                     | PDF Toolbox JAR file `com.pdf_tools.fourheights.pdftoolbox.jar`                                                                                                       |
| The 64-bit native library for the respective platform: `PdfToolboxAPI.dll`, `libPdfToolboxAPI.so`, or `libPdfToolboxAPI.dylib`. (For Windows, also the 32-bit library.) | The native libraries for all supported platforms (Windows 64-bit and 32-bit, Linux 64-bit, macOS 64-bit): `PdfToolbox.dll`, `libPdfToolbox.so`, `libPdfToolbox.dylib` |
| A graphical license management tool or the license management shell tool                                                                                                | The license management tools are no longer necessary. See [License keys](#license-keys)                                                                               |
| Manual and JavaDoc API reference                                                                                                                                        | Manual and JavaDoc API reference                                                                                                                                      |
| Samples                                                                                                                                                                 | Samples are no longer provided in the kit, but are available [online](../code-samples/README.mdx).                                                                    |

| 3-Heights® PDF Toolbox API                                                                                                                                              | PDF Toolbox SDK                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [C header files](#c-header-files)                                                                                                                                       | [C header files](#c-header-files)                                                                                                                                     |
| The 64-bit native library for the respective platform: `PdfToolboxAPI.dll`, `libPdfToolboxAPI.so`, or `libPdfToolboxAPI.dylib`. (For Windows, also the 32-bit library.) | The native libraries for all supported platforms (Windows 64-bit and 32-bit, Linux 64-bit, macOS 64-bit): `PdfToolbox.dll`, `libPdfToolbox.so`, `libPdfToolbox.dylib` |
| A graphical license management tool or the license management shell tool                                                                                                | The license management tools are no longer necessary. See [License keys](#license-keys)                                                                               |
| Manual                                                                                                                                                                  | Manual                                                                                                                                                                |
| Samples                                                                                                                                                                 | Samples are no longer provided in the kit, but are available [online](../code-samples/README.mdx).                                                                    |

C header files

In 3-Heights® PDF Toolbox API, there is one main header `filepdftoolboxapi_c.h`, which included the additional header `filespdfcdecl.h`, `pdfcopydecl.h`, `pdffiledecl.h`, `pdfintfdecl.h`, and `pdfsecuritydecl.h`.

In the PDF Toolbox SDK, there is one main header `filePdfToolbox.h`, which includes the following subheader files:

- `PdfToolbox_Platform.h`: A platform abstraction header file.
- `PdfToolbox_Types.h`: Declaration of all types.
- `PdfToolbox_‹prefix›.h`: Subheader file for each ‹prefix› (seePrefixes), containing function declarations.

## License keys

The 3-Heights® PDF Toolbox API supports the installation of machine-bound license 3-Heights® license keys by means of the graphical tool `LicenseManager.exe` for Windows or the shell `toollicmgr` for all platforms.

The PDF Toolbox SDK does not support installed keys anymore. Instead, a license key must be provided at application initialization time. See also `The Sdk functions`.Additionally, the license key has a new format: ``.

## Changes to the interface

See [.NET interface](dotnet-interface.mdx)

See [Java interface](./java-interface.mdx)

See [C interface](C-interface.mdx)

---

## Reference for changes in C interface

This section lists all changes in the C interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK prefix.

## Prefix Ptx

Changes to functions that are not related to specific object types:

- Removed `functionPdfClose`. Substituted for closeable objects by explicit `..._Close` functions. See [Closing and releasing](./C-interface.mdx#closing-and-releasing).
- Removed `PdfCheckLicense`.
- Functions moved to `TPtx_Sdk`:

  - `PdfSetLicenseKey`
  - `PdfGetProductVersion` See [License keys and product version](./README.mdx#license-keys).

- Renamed functions:

  | 3-Heights® PDF Toolbox API function | PDF Toolbox SDK function  |
  | ----------------------------------- | ------------------------- |
  | `PdfInitialize`                     | `Ptx_Initialize`          |
  | `PdfUninitialize`                   | `Ptx_Uninitialize`        |
  | `PdfGetLastError`                   | `Ptx_GetLastError`        |
  | `PdfGetLastErrorMessage`            | `Ptx_GetLastErrorMessage` |
  | `PdfRelease`                        | `Ptx_Release`             |
  | `PdfEquals`                         | `Ptx_Equals`              |
  | `PdfGetHashCode`                    | `Ptx_GetHashCode`         |

#### TPdfErrorCode

| [Enum.] `TPdfErrorCode` → `TPtx_ErrorCode`                                                                               |
| ------------------------------------------------------------------------------------------------------------------------ |
| Removed enum values:  `ePdfErrorInfrastructure``ePdfErrorProcessing``ePdfErrorFatal` |
| Renamed enum value:  `ePdfSuccess` → `ePdf_Error_Success` `ePdfError...` → `ePdf_Error_...`   |

#### TPtx_Sdk

| [Class] `TPtx_Sdk` → `TPtx_Sdk`                                                                                     |
| ------------------------------------------------------------------------------------------------------------------- |
| Related function: `BOOL Ptx_Sdk_Initialize(` `const char* szLicense,``const char* szProducerSuffix)` |
| Related function: `size_t Ptx_Sdk_GetVersion(``char* pBuffer,` `size_tnBufferSize)`                  |
| Related function: `size_t Ptx_Sdk_GetProducerFullName(``char* pBuffer,``size_tnBufferSize)`          |

See the [Sdk functions](C-interface.mdx#the-sdk-functions)

#### TPdfStringMap

| [Class] `TPdfStringMap` → `TPtxPdf_StringMap`                               |
| --------------------------------------------------------------------------- |
| Renamed value: `PdfStringMap...` → `PtxPdf_StringMap_...` |

## Prefix PtxGeom

#### TdfRotation

| [Enum.] `TPdfRotation` → `TPtxGeom_Rotation`                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed values: `ePdfRotateNoRotation` → `ePtxGeom_Rotation_None`` ePdfRotateClockwise` → `ePtxGeom_Rotation_Clockwise``ePdfRotateUpsideDown` → `ePtxGeom_Rotation_UpsideDown` `ePdfRotateCounterClockwise` → `ePtxGeom_Rotation_CounterClockwise` |

#### TPdfTextAlignment

| [Enum.] `TPdfTextAlignment` → `TPtxGeom_HorizontalAlignment`                                   |
| ---------------------------------------------------------------------------------------------- |
| Renamed value:  `ePdfTextAlignment...` → `ePtxGeom_HorizontalAlignment_...`  |

### Prefix PtxGeomInt

#### TPtxGeomInt_Size

| [Struct.] `TPtxGeomInt_Size` → `TPtxGeomInt_Size`                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fields: `intiWidth` `intiHeight` Used in `TPdfImage` and `TPdfImageMask` to substitute the removed related functions `PdfImageGetWidth`, `PdfImageGetHeight`, `PdfImageMaskGetWidth`, and `PdfImageMaskGetHeight`. |

See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size).

### Prefix PtxGeomReal

#### TPdfPoint

| [Struct.] `TPdfPoint` → `TPtxGeomReal_Point` |
| -------------------------------------------- |

#### TPdfRectangle

| [Struct.] `TPdfRectangle` → `TPtxGeomReal_Rectangle` |
| ---------------------------------------------------- |

#### TPdfSize

| [Struct.] `TPdfSize` → `PtxGeomReal_Size` |
| ----------------------------------------- |

#### TPdfTransformation

| [Class] → [Struct.] `TPdfTransformation` → `TPtxGeomReal_AffineTransform`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions:  `PdfNewTransformationIdentity`, `PdfNewTransformationCopy`, and `PdfNewTransformation`.Removed related function: `PdfTransformationRotate` Renamed related function:  `PdfTransformationRotateAround` → `PtxGeomReal_AffineTransform_Rotate`.Renamed remaining related functions: `PdfTransformation...` → `PtxGeomReal_AffineTransform_...` New fields: `double dA` `double dB`  `double dC`  `double dD`  `double dE` `double dF` New related function:  `BOOL PtxGeomReal_AffineTransform_GetIdentity(`  `TPtxGeomReal_AffineTransform* pIdentity)`. See [Affine transform objects should be initialized](C-interface.mdx#affine-transform-objects-should-be-initialized). |

See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct)

## Prefix PtxPdf

#### TPdfConformance

| [Enum.] `TPdfConformance` → `TPtxPdf_Conformance`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum value `ePdfUnk`Renamed enum values:  `ePdfA1b` → `ePtxPdf_Conformance_PdfA1B``ePdfA1a` → `ePtxPdf_Conformance_PdfA1A``ePdfA2b` → `ePtxPdf_Conformance_PdfA2B``ePdfA2u` → `ePtxPdf_Conformance_PdfA2U``ePdfA2a` → `ePtxPdf_Conformance_PdfA2A``ePdfA3b` → `ePtxPdf_Conformance_PdfA3B``ePdfA3u` → `ePtxPdf_Conformance_PdfA3U``ePdfA3a` → `ePtxPdf_Conformance_PdfA3A`Renamed remaining enum values `ePdf...` → `ePtxPdf_Conformance_...` |

#### TPdfCopyOption

| [Enum.] `TPdfCopyOption` → -                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| Substituted by `TPtxPdf_PageCopyOptions` and `TPtxPdfNav_OutlineCopyOptions`. See [Copy options](C-interface.mdx#copy-options). |

| [Enum.] - → `TPtxPdf_CopyStrategy`                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:  `ePtxPdf_CopyStrategy_Copy``ePtxPdf_CopyStrategy_Flatten``ePtxPdf_CopyStrategy_Remove`Substitutes the removed `TPdfCopyOption`. |

#### TPdfDocument

| [Class] `TPdfDocument` → `TPtxPdf_Document`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfDocumentGetOutlineItems`→ `PtxPdf_Document_GetOutline`. Changed return and argument type of related functions `PdfDocumentGetOutputIntent` and `PdfDocumentSetOutputIntent` from `TPdfColorSpace` to `TPtxPdfContent_IccBasedColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes).Renamed related function `PdfDocumentGetEmbeddedFiles` → `PtxPdf_Document_GetAllEmbeddedFiles`. Changed behavior: Appending is not supported anymore. This is a readonly list of all embedded files and all files in `TPdfFileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./C-interface.mdx#embeddedassociatedattached-files).Changed behavior of related function `PdfDocumentGetConformance` → `PtxPdf_Document_GetConformance` for output documents: Always returns the current conformance instead of removed enum value `ePdfUnk`.Changed signature of related function `TPdfDocument* PdfDocumentCreate(``TPdfstream* pStreamDesc,``TPdfConformance iConformance,``TPdfEncryptionParams* pEncryption)` → `TPtxPdf_Document* PtxPdf_Document_Create(``TPtxSys_StreamDescriptor* pStreamDesc,``TPtxPdf_Conformance* pConformance,``TPtxPdf_Encryption* pEncryption)`Specifically, a `NULL` value for the second argument is now legal. See [Unknown PDF conformance](./C-interface.mdx#unknown-pdf-conformance).Removed and substituted the following related functions:`PdfDocumentCreateFileReference` → `PtxPdf_FileReference_Create``PdfDocumentCreateMetadata` → `PtxPdf_Metadata_Create``PdfDocumentCreatePage` → `PtxPdf_Page_Create``PdfDocumentCreateCircleAnnotation` → `PtxPdfAnnots_EllipseAnnotation_Create``PdfDocumentCreateCustomStampAnnotation` → `PtxPdfAnnots_CustomStamp_Create``PdfDocumentCreateFileAttachmentAnnotation` → `PtxPdfAnnots_FileAttachment_Create``PdfDocumentCreateFreeDrawingAnnotation` → `PtxPdfAnnots_InkAnnotation_Create``PdfDocumentCreateFreeTextAnnotation` → `PtxPdfAnnots_FreeText_Create``PdfDocumentCreateLineAnnotation` → `PtxPdfAnnots_LineAnnotation_Create``PdfDocumentCreatePolyLineAnnotation` → `PtxPdfAnnots_PolyLineAnnotation_Create``PdfDocumentCreatePolygonAnnotation` → `PtxPdfAnnots_PolygonAnnotation_Create``PdfDocumentCreateSquareAnnotation` → `PtxPdfAnnots_RectangleAnnotation_Create``PdfDocumentCreateStickyNoteAnnotation` → `PtxPdfAnnots_StickyNote_Create``PdfDocumentCreateTextStampAnnotationRaw` → `PtxPdfAnnots_TextStamp_CreateRaw``PdfDocumentCreateAlphaPaint`, `PdfDocumentCreateBlendingPaint`, `PdfDocumentCreateSolidPaint` → `PtxPdfContent_Paint_Create` See [Unified paint creation](./C-interface.mdx#unified-paint-creation).`PdfDocumentCreateDeviceColorSpace` → `PtxPdfContent_ColorSpace_CreateProcessColorSpace``PdfDocumentCreateFont` → `PtxPdfContent_Font_Create``PdfDocumentCreateGroup` → `PtxPdfContent_Group_Create``PdfDocumentCreateICCColorSpace` → `PtxPdfContent_IccBasedColorSpace_Create``PdfDocumentCreateImageMask` → `PtxPdfContent_ImageMask_Create``PdfDocumentCreateImage` → `PtxPdfContent_Image_Create``PdfDocumentCreateSystemFont` → `PtxPdfContent_Font_CreateFromSystem``PdfDocumentCreateText` → `PtxPdfContent_Text_Create``PdfDocumentCreateCheckBoxField` → `PtxPdfForms_CheckBoxField_Create``PdfDocumentCreateCombTextField` → `PtxPdfForms_CombTextField_Create``PdfDocumentCreateComboBoxField` → `PtxPdfForms_ComboBoxField_Create``PdfDocumentCreateGeneralTextField` → `PtxPdfForms_GeneralTextField_Create``PdfDocumentCreateListBoxField` → `PtxPdfForms_ListBoxField_Create``PdfDocumentCreateRadioButtonField` → `PtxPdfForms_RadioButtonField_Create``PdfDocumentCreateSubForm` → `PtxPdfForms_SubForm_Create``PdfDocumentCreateNamedDestination` → `PtxPdfNav_NamedDestination_Create``PdfDocumentCreateOutlineItem` → `PtxPdfNav_OutlineItem_Create``PdfDocumentCopyFileReference` → `PtxPdf_FileReference_Copy``PdfDocumentCopyMetadata` → `PtxPdf_Metadata_Copy``PdfDocumentCopyPage` → `PtxPdf_Page_Copy``PdfDocumentCopyAnnotation` → `PtxPdfAnnots_Annotation_Copy``PdfDocumentCopyColorSpace` → `PtxPdfContent_ColorSpace_Copy``PdfDocumentCopyContentElement` → `PtxPdfContent_ContentElement_Copy``PdfDocumentCopyGroupElementWithoutContent` → `PtxPdfContent_GroupElement_CopyWithoutContent``PdfDocumentCopyPageAsGroup` → `PtxPdfContent_Group_CopyFromPage``PdfDocumentCopyFormFieldNode` → `PtxPdfForms_FormFieldNode_Copy``PdfDocumentCopyViewerSettings` → `PtxPdfNav_ViewerSettings_Copy``PdfDocumentCopyOutlineItem` → `PtxPdfNav_OutlineItem_Copy` See [Creation and copying methods](././C-interface.mdx#creation-and-copying-methods).Renamed remaining related functions `PdfDocument...` → `PtxPdf_Document_...`New related function `TPtxPdf_FileReferenceList* PtxPdf_Document_GetPlainEmbeddedFiles(` `TPtxPdf_Document* )`. This is a list of all embedded files that are neither associated nor contained in a `TPdfFileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./C-interface.mdx#embeddedassociatedattached-files).New related function `BOOL PtxPdf_Document_Close(``TPtxPdf_Document*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing). |

#### TPdfEncryptionParams

| [Struct.] → [Class] `TPdfEncryptionParams` → `TPtxPdf_Encryption`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfEncryptionParamsInitialize`.New related function `TPtxPdf_Encryption* PtxPdf_Encryption_New(``const char* szUserPassword,``const char* szOwnerPassword,``TPtxPdf_Permission iPermissions)`.New related functions `size_t PtxPdf_Encryption_GetUserPassword(`  `TPtxPdf_Encryption*,` `char* pBuffer,``size_t nBufferSize)` `size_t PtxPdf_Encryption_SetUserPassword(` `TPtxPdf_Encryption*,` `const char* szUserPassword)`. New related functions `size_t PtxPdf_Encryption_GetOwnerPassword(` `TPtxPdf_Encryption*,` `char* pBuffer,size_tnBufferSize)`  `size_t PtxPdf_Encryption_SetOwnerPassword(`  `TPtxPdf_Encryption*,` `const char*szOwnerPassword)`. New related functions `TPtxPdf_Permission`  `PtxPdf_Encryption_GetPermissions(`  `TPtxPdf_Encryption*)`  `BOOL PtxPdf_Encryption_SetPermissions(` `TPtxPdf_Encryption*,` `TPtxPdf_PermissioniPermissions)`. |

#### TPdfFileReference

| [Class] `TPdfFileReference` → `TPtxPdf_FileReference`                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFileReference...` → `PtxPdf_FileReference_...` New related function `TPtxPdf_FileReference* PtxPdf_FileReference_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxSys_StreamDescriptor* pData,`  `const char* szName,` `const char* szMediaType,` `const char* szDescription,` `TPtxSys_Date* pModificationDate)` |

See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).

#### TPdfFileReferenceList

| [Class] `PdfFileReferenceList` → `TPtxPdf_FileReferenceList`                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFileReferenceListAppend` → `PtxPdf_FileReferenceList_Add`.Renamed remaining related functions `PdfFileReferenceList...`→ `PtxPdf_FileReferenceList_...`  |

#### TPdfMetadata

| [Class] `TPdfMetadata` → `TPtxPdf_Metadata`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfMetadataSetProducer`. See The PDF Producer entry.Renamed related functions `PdfMetadata...` → `PtxPdf_Metadata_...`New related function `TPtxPdf_Metadata* PtxPdf_Metadata_Create(`  `TPtxPdf_Document* pTargetDocument,` `TPtxSys_StreamDescriptor* pXmp)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdf_Metadata* PtxPdf_Metadata_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdf_Metadata* pMetadata)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPtxPdf_NameConflictResolution

| [Enum.] - → `TPtxPdf_NameConflictResolution`                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `ePtxPdf_NameConflictResolution_Merge``ePtxPdf_NameConflictResolution_Rename` Substitutes the removed `TPdfCopyOption` |

See [Copy options](C-interface.mdx#copy-options).

#### TPdfPage

| [Class] `TPdfPage` → `TPtxPdf_Page`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfPageCrop` → `PtxPdf_Page_UpdateSize`.Renamed remaining related functions `PdfPage...` → `PtxPdf_Page_...`New related function `TPtxPdfForms_WidgetList* PtxPdf_Page_GetFormFieldWidgets(` `TPtxPdf_Page*)`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfNav_LinkList* PtxPdf_Page_GetLinks(` `TPtxPdf_Page*)`.See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdf_Page* PtxPdf_Page_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Size* pSize)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdf_Page* PtxPdf_Page_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdf_Page* pPage,` `TPtxPdf_PageCopyOptions* pOptions)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPtxPdf_PageCopyOptions

| [Class] - → `TPtxPdf_PageCopyOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Related function `TPtxPdf_PageCopyOptions* PtxPdf_PageCopyOptions_New()`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetLinks(` `TPtxPdf_PageCopyOptions*)` `BOOL PtxPdf_PageCopyOptions_SetLinks(` `TPtxPdf_PageCopyOptions*,` `TPtxPdf_CopyStrategyiLinks)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `TPtxPdfForms_FormFieldCopyStrategy PtxPdf_PageCopyOptions_GetFormFields(` `TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetFormFields(``TPtxPdf_PageCopyOptions*,``TPtxPdfForms_FormFieldCopyStrategyiFormFields)`Default: `ePtxPdfForms_FormFieldCopyStrategy_Copy`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetSignedSignatures(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetSignedSignatures(``TPtxPdf_PageCopyOptions*,``TPtxPdf_CopyStrategyiSignedSignatures)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `TPtxPdf_CopyStrategy PtxPdf_PageCopyOptions_GetAnnotations(` `TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetAnnotations(` `TPtxPdf_PageCopyOptions*,` `TPtxPdf_CopyStrategyiAnnotations)`Default: `ePtxPdf_CopyStrategy_Copy`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyOutlineItems(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyOutlineItems(``TPtxPdf_PageCopyOptions*,``BOOL bCopyOutlineItems)`Default: `TRUE`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyAssociatedFiles(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyAssociatedFiles(``TPtxPdf_PageCopyOptions*,``BOOL bCopyAssociatedFiles)`Default: `TRUE`Related functions `BOOL PtxPdf_PageCopyOptions_GetCopyLogicalStructure(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetCopyLogicalStructure(``TPtxPdf_PageCopyOptions*,``BOOL bCopyLogicalStructure)`Default: `TRUE`Related functions `TPtxPdf_NameConflictResolution PtxPdf_PageCopyOptions_GetFormFieldConflictResolution(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetFormFieldConflictResolution(``TPtxPdf_PageCopyOptions*,``TPtxPdf_NameConflictResolution iFormFieldConflictResolution)`Default: `ePtxPdf_NameConflictResolution_Merge`Related functions `TPtxPdfNav_NamedDestinationCopyStrategy PtxPdf_PageCopyOptions_GetNamedDestinations(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetNamedDestinations(``TPtxPdf_PageCopyOptions*,``TPtxPdfNav_NamedDestinationCopyStrategy iNamedDestinations)`Default: `ePtxPdfNav_NamedDestinationCopyStrategy_Copy`Related functions `BOOL PtxPdf_PageCopyOptions_GetOptimizeResources(``TPtxPdf_PageCopyOptions*)``BOOL PtxPdf_PageCopyOptions_SetOptimizeResources(``TPtxPdf_PageCopyOptions*,``BOOL bOptimizeResources)`Default: `TRUE` Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |

#### TPdfPageList

| [Class] `TPdfPageList` → `TPtxPdf_PageList`                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfPageListAppend` → `PtxPdf_PageList_Add`Renamed remaining related functions `PdfPageList...` → `PtxPdf_PageList_...` |

#### TPdfPermission

| [Enum.] `TPdfPermission` → `TPtxPdf_Permission`                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values `ePermAll`, `ePermSameAsInput`, and `ePermNoEncryption`.Renamed enum values `ePerm...` → `ePtxPdf_Permission_...` |

#### TPtxPdf_RemovalStrategy

| [Enum.] - → `TPtxPdf_RemovalStrategy`                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Values: `ePtxPdf_RemovalStrategy_Flatten` `ePtxPdf_RemovalStrategy_Remove`  Substitutes the removed `TPdfCopyOption`. |

See [Copy options](C-interface.mdx#copy-options).

### Prefix PtxPdfAnnots

#### TPdfAnnotation

| [Class] `TPdfAnnotation` → `TPtxPdfAnnots_Annotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfAnnotationGetRectangle` → `PtxPdfAnnots_Annotation_GetBoundingBox` Removed related function `PdfAnnotationGetDoPrint` New related function `PtxPdfAnnots_Annotation_GetNoPrint` with reversed meaning of the removed related function `PdfAnnotationGetDoPrint`.New related function `TPtxPdfAnnots_Annotation* PtxPdfAnnots_Annotation_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfAnnots_Annotation* pAnnotation)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Annotations](C-interface.mdx#annotations). |

#### TPdfAnnotationLineEnding

| [Enum.] `TPdfAnnotationLineEnding` → `TPtxPdfAnnots_LineEnding`                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `ePdfAnnotationLineEndingReversedOpenArrow` → `ePtxPdfAnnots_LineEnding_OpenArrowTail` Renamed enum value `ePdfAnnotationLineEndingReversedClosedArrow` → `ePtxPdfAnnots_LineEnding_ClosedArrowTail`Renamed remaining enum values `ePdfAnnotationLineEnding...` → `ePtxPdfAnnots_LineEnding_...` |

#### TPdfAnnotationsList

| [Class] `TPdfAnnotationList`→ `TPtxPdfAnnots_AnnotationList`                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfAnnotationListAppend` → `PtxPdfAnnots_AnnotationList_Add`.Renamed remaining related functions `PdfAnnotationList...` → `PtxPdfAnnots_AnnotationList_...` |

#### TPdfAnnotationPopup

| [Class] `TPdfAnnotationPopup` → `TPtxPdfAnnots_Popup`                                            |
| ------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfAnnotationPopupGetRectangle` → `PtxPdfAnnots_Popup_GetBoundingBox`. |

#### TPdfAnnotationType

| [Enum.] `TPdfAnnotationType` → `TPtxPdfAnnots_AnnotationType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed enum values:`ePdfAnnotationTypeWidget``ePdfAnnotationTypeLink``ePdfAnnotationTypeInternalLink``ePdfAnnotationTypeWebLink``ePdfAnnotationTypeEmbeddedPdfLink``ePdfAnnotationTypePolyDrawingAnnotation``ePdfAnnotationTypeShapeDrawingAnnotation`Renamed enum values:`ePdfAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_AnnotationType_EllipseAnnotation``ePdfAnnotationTypeCustomStampAnnotation` → `ePtxPdfAnnots_AnnotationType_CustomStamp``ePdfAnnotationTypeFileAttachmentAnnotation` → `ePtxPdfAnnots_AnnotationType_FileAttachment``ePdfAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_AnnotationType_InkAnnotation``ePdfAnnotationTypeFreeTextAnnotation` → `ePtxPdfAnnots_AnnotationType_FreeText``ePdfAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_AnnotationType_Highlight``ePdfAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_AnnotationType_RectangleAnnotation``ePdfAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_AnnotationType_Squiggly``ePdfAnnotationTypeStampAnnotation` → `ePtxPdfAnnots_AnnotationType_Stamp``ePdfAnnotationTypeStickyNoteAnnotation` → `ePtxPdfAnnots_AnnotationType_StickyNote``ePdfAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_AnnotationType_StrikeThrough``ePdfAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_AnnotationType_TextInsert``ePdfAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_AnnotationType_TextMarkup``ePdfAnnotationTypeTextStampAnnotation` → `ePtxPdfAnnots_AnnotationType_TextStamp``ePdfAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_AnnotationType_Underline`Renamed remaining enum values `ePdfAnnotationType...` → `ePtxPdfAnnots_AnnotationType_...` See [Annotations](C-interface.mdx#annotations). |

#### TPdfCircleAnnotation

| [Class] `TPdfCircleAnnotation[class]` → `TPtxPdfAnnots_EllipseAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See Annotations. New related function `TPtxPdfAnnots_EllipseAnnotation* PtxPdfAnnots_EllipseAnnotation_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `TPtxPdfContent_Stroke* pStroke,` `TPtxPdfContent_Paint* pFill)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Paint* PtxPdfAnnots_EllipseAnnotation_GetFill(` `TPtxPdfAnnots_EllipseAnnotation*)`.See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfCustomStampAnnotation

| [Class] `TPdfCustomStampAnnotation` → ` TPtxPdfAnnots_CustomStamp`                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Renamed related functions `PdfCustomStampAnnotation...` → `PtxPdfAnnots_CustomStamp_...`New related function `TPtxPdfAnnots_CustomStampAnnotation* PtxPdfAnnots_CustomStamp_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfStampAnnotation](#tpdfstampannotation) for inherited changes.  |

#### TPdfDrawingAnnotation

| [Class] `TPdfDrawingAnnotation` → ` TPtxPdfAnnots_DrawingAnnotation`                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfDrawingAnnotation...` → `PtxPdfAnnots_DrawingAnnotation_...` See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |

#### TPdfDrawingAnnotationType

| [Enum.] `TPdfDrawingAnnotationType` → ` TPtxPdfAnnots_DrawingAnnotationType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values: `ePdfDrawingAnnotationTypePolyDrawingAnnotation``ePdfDrawingAnnotationTypeShapeDrawingAnnotation`Renamed enum values:`ePdfDrawingAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_EllipseAnnotation``ePdfDrawingAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_InkAnnotation``ePdfDrawingAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_DrawingAnnotationType_RectangleAnnotation`Renamed remaining enum values `ePdfDrawingAnnotationType...` → `ePtxPdfAnnots_DrawingAnnotationType_...` See [Annotations](C-interface.mdx#annotations). |

#### TPdfFileAttachmentAnnotation

| [Class] `TPdfFileAttachmentAnnotation` → ` TPtxPdfAnnots_FileAttachment`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New related function `TPtxPdfAnnots_FileAttachmentAnnotation* PtxPdfAnnots_FileAttachment_Create(``TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Point* pTopleft,``TPtxPdf_FileReference* pAttachedFile,``TPtxPdfContent_Paint* pPaint)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).Renamed related functions `PdfFileAttachmentAnnotation...` → `PtxPdfAnnots_FileAttachment_...`See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |

#### TPdfFileAttachmentIcon

| [Enum.] `TPdfFileAttachmentIcon` → ` TPtxPdfAnnots_FileAttachmentIcon`                   |
| ---------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfFileAttachmentIcon...` → `ePtxPdfAnnots_FileAttachmentIcon_...` |

#### TPdfFreeDrawingAnnotation

| [Class] `TPdfFreeDrawingAnnotation` → ` TPtxPdfAnnots_InkAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfAnnots_InkAnnotation* PtxPdfAnnots_InkAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_Path* pPath,` `TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfFreeTextAnnotation

| [Class] `TPdfFreeTextAnnotation` → ` TPtxPdfAnnots_FreeText`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfFreeTextAnnotation...` → `PtxPdfAnnots_FreeText_...`New related function `TPtxPdfAnnots_FreeText* PtxPdfAnnots_FreeText_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `const char* szContent,`  `TPtxPdfContent_Paint* pPaint)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes.  |

#### TPdfHighlightAnnotation

| [Class] `TPdfHighlightAnnotation` → ` TPtxPdfAnnots_Highlight`                   |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |

#### TPdfLineAnnotation

| [Class] `TPdfLineAnnotation` → ` TPtxPdfAnnots_LineAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfLineAnnotation...` → `PtxPdfAnnots_LineAnnotation_...`New related function  `TPtxPdfAnnots_LineAnnotation* PtxPdfAnnots_LineAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Point* pStart,` `TPtxGeomReal_Point* pEnd,``TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfMarkupAnnotation

| [Class] `TPdfMarkupAnnotation` → ` TPtxPdfAnnots_MarkupAnnotation`                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfMarkupAnnotation...` → `PtxPdfAnnots_MarkupAnnotation_...` See [TPdfAnnotation](#tpdfannotation) for inherited changes. |

#### TPdfMarkupAnnotationType

| [Enum.] `TPdfMarkupAnnotationType` → ` TPtxPdfAnnots_MarkupAnnotationType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum values: `ePdfMarkupAnnotationTypePolyDrawingAnnotation``ePdfMarkupAnnotationTypeShapeDrawingAnnotation`Renamed enum values: `ePdfMarkupAnnotationTypeCircleAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_EllipseAnnotation``ePdfMarkupAnnotationTypeCustomStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_CustomStamp``ePdfMarkupAnnotationTypeDrawingAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_DrawingAnnotation``ePdfMarkupAnnotationTypeFileAttachmentAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_FileAttachment``ePdfMarkupAnnotationTypeFreeDrawingAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_InkAnnotation``ePdfMarkupAnnotationTypeFreeTextAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_FreeText``ePdfMarkupAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Highlight``ePdfMarkupAnnotationTypeSquareAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_RectangleAnnotation``ePdfMarkupAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Squiggly``ePdfMarkupAnnotationTypeStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Stamp``ePdfMarkupAnnotationTypeStickyNoteAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_StickyNote``ePdfMarkupAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_StrikeThrough``ePdfMarkupAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextInsert``ePdfMarkupAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextMarkup``ePdfMarkupAnnotationTypeTextStampAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_TextStamp``ePdfMarkupAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_MarkupAnnotationType_Underline`Renamed remaining enum values `ePdfMarkupAnnotationType...` → `ePtxPdfAnnots_MarkupAnnotationType_...`See [Annotations](C-interface.mdx#annotations). |

#### TPdfMarkupInfo

| [Class] `TPdfMarkupInfo` → ` TPtxPdfAnnots_MarkupInfo`                       |
| ---------------------------------------------------------------------------- |
| Renamed related functions `PdfMarkupInfo...` → `PtxPdfAnnots_MarkupInfo_...` |

#### TPdfMarkupInfoList

| [Class] `TPdfMarkupInfoList` → ` TPtxPdfAnnots_MarkupInfoList`                                 |
| ---------------------------------------------------------------------------------------------- |
| Renamed remaining related functions `PdfMarkupInfoList...` → `PtxPdfAnnots_MarkupInfoList_...` |

#### TPdfPolyDrawingAnnotation

| `TPdfPolyDrawingAnnotation[class]`                       |
| -------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |

#### TPdfPolyDrawingAnnotationType

| `TPdfPolyDrawingAnnotationType[enum]` → ` TPtx_PolyDrawingAnnotationType` |
| ------------------------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations).                  |

#### TPdfPolyLineAnnotation

| `TPdfPolyLineAnnotation[class]` → ` TPtxPdfAnnots_PolyLineAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`.See [Annotations](C-interface.mdx#annotations).Renamed related functions `PdfPolyLineAnnotation...` → `PtxPdfAnnots_PolyLineAnnotation_...`New related function  `TPtxPdfAnnots_PolyLineAnnotation* PtxPdfAnnots_PolyLineAnnotation_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_Path* pPath,``TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfPolygonAnnotation

| [Class] `TPdfPolygonAnnotation` → ` TPtxPdfAnnots_PolygonAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations).  Renamed related functions `PdfPolygonAnnotation...` → `PtxPdfAnnots_PolygonAnnotation_...`New related function `TPtxPdfAnnots_PolygonAnnotation* PtxPdfAnnots_PolygonAnnotation_Create(`  `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_Path* pPath,`  `TPtxPdfContent_Stroke* pStroke)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfShapeDrawingAnnotation

| [Class] `TPdfShapeDrawingAnnotation`                     |
| -------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations). |

#### TPdfShapeDrawingAnnotationType

| [Enum.] `TPdfShapeDrawingAnnotationType` → ` TPtx_ShapeDrawingAnnotationType` |
| ----------------------------------------------------------------------------- |
| Removed. See [Annotations](C-interface.mdx#annotations).                      |

#### TPdfSquareAnnotation

| [Class] `TPdfSquareAnnotation` → ` TPtxPdfAnnots_RectangleAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to struct `TPtxPdfAnnots_DrawingAnnotation`. See [Annotations](C-interface.mdx#annotations).New related function `TPtxPdfAnnots_PolylineAnnotation* PtxPdfAnnots_RectangleAnnotation_Create(`  `TPtxPdf_Document* pTargetDocument,` `TPtxGeomReal_Rectangle* pBoundingBox,` `TPtxPdfContent_Stroke* pStroke,`  `TPtxPdfContent_Fill* pFill)`  See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Fill* PtxPdfAnnots_RectangleAnnotation_GetFill(``TPtxPdfAnnots_RectangleAnnotation*)`.See [TPdfDrawingAnnotation](#tpdfdrawingannotation) for inherited changes. |

#### TPdfSquigglyAnnotation

| [Class] `TPdfSquigglyAnnotation` → ` TPtxPdfAnnots_Squiggly`                   |
| ------------------------------------------------------------------------------ |
| See [TPdfHighlightAnnotation](#tpdfhighlightannotation) for inherited changes. |

#### TPdfStampAnnotation

| [Class] `TPdfStampAnnotation` → ` TPtxPdfAnnots_Stamp`                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfStampAnnotation...` → `PtxPdfAnnots_Stamp_...` See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |

#### TPdfStampAnnotationType

| [Enum.] `TPdfStampAnnotationType` → ` TPtxPdfAnnots_StampType`                   |
| -------------------------------------------------------------------------------- |
| Renamed enum values `ePdfStampAnnotationType...` → `ePtxPdfAnnots_StampType_...` |

#### TPdfStickyNoteAnnotation

| [Class] `TPdfStickyNoteAnnotation` → ` TPtxPdfAnnots_StickyNote`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfStickyNoteAnnotation...` → `PtxPdfAnnots_StickyNote_...`New related function `TPtxPdfAnnots_StickyNote* PtxPdfAnnots_StickyNote_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Point* pTopleft,`,br/`const char* szContent,` `TPtxPdfContent_Paint*pPaint)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |

#### TPdfStrikeThroughAnnotation

| [Class] `TPdfStrikeThroughAnnotation` → ` TPtxPdfAnnots_StrikeThrough`           |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |

#### TPdfTextInsertAnnotation

| [Class] `TPdfTextInsertAnnotation` → ` TPtxPdfAnnots_TextInsert`                 |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |

#### TPdfTextMarkupAnnotation

| [Class] `TPdfTextMarkupAnnotation` → ` TPtxPdfAnnots_TextMarkup`         |
| ------------------------------------------------------------------------ |
| See [TPdfMarkupAnnotation](#tpdfmarkupannotation) for inherited changes. |

#### TPdfTextMarkupAnnotationType

| [Enum.] `TPdfTextMarkupAnnotationType` → ` TPtxPdfAnnots_TextMarkupType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:  `ePdfTextMarkupAnnotationTypeHighlightAnnotation` → `ePtxPdfAnnots_TextMarkupType_Highlight` `ePdfTextMarkupAnnotationTypeSquigglyAnnotation` → `ePtxPdfAnnots_TextMarkupType_Squiggly` `ePdfTextMarkupAnnotationTypeStrikeThroughAnnotation` → `ePtxPdfAnnots_TextMarkupType_StrikeThrough` `ePdfTextMarkupAnnotationTypeTextInsertAnnotation` → `ePtxPdfAnnots_TextMarkupType_TextInsert` `ePdfTextMarkupAnnotationTypeTextMarkupAnnotation` → `ePtxPdfAnnots_TextMarkupType_TextMarkup` `ePdfTextMarkupAnnotationTypeUnderlineAnnotation` → `ePtxPdfAnnots_TextMarkupType_Underline` |

#### TPdfTextStampAnnotation

| [Class] `TPdfTextStampAnnotation` → ` TPtxPdfAnnots_TextStamp`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New related function  `TPtxPdfAnnots_TextStamp* PtxPdfAnnots_TextStamp_Create(` `TPtxPdf_Document* pTargetDocument,`  `TPtxGeomReal_Point* pTopleft,`  `const double* pHeight,` `TPtxPdfAnnots_TextStampTypeiType,`  `const char*szContent)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).Renamed related functions `PdfTextStampAnnotation...` → `PtxPdfAnnots_TextStamp_...` See [TPdfStampAnnotation](#tpdfstampannotation) for inherited changes. |

#### TPdfTextStampType

| [Enum.] `TPdfTextStampType` → ` TPtxPdfAnnots_TextStampType`                   |
| ------------------------------------------------------------------------------ |
| Renamed enum values `ePdfTextStampType...` → `ePtxPdfAnnots_TextStampType_...` |

#### TPdfUnderlineAnnotation

| [Class] `TPdfUnderlineAnnotation` → ` TPtxPdfAnnots_Underline`                   |
| -------------------------------------------------------------------------------- |
| See [TPdfTextMarkupAnnotation](#tpdftextmarkupannotation) for inherited changes. |

### Prefix PtxPdfContent

#### TPdfBlendMode

| [Enum.] `TPdfBlendMode` → ` TPtxPdfContent_BlendMode`                   |
| ----------------------------------------------------------------------- |
| Renamed enum values `ePdfBlendMode...` → `ePtxPdfContent_BlendMode_...` |

#### TPtxPdfContent_CalibratedGrayColorSpace

| [Class] `TPtxPdfContent_CalibratedGrayColorSpace`                                                    |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPtxPdfContent_CalibratedRgbColorSpace

| [Class] `TPtxPdfContent_CalibratedRgbColorSpace`                                                     |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPtxPdfContent_CalibratedCmykColorSpace

| [Class] `TPtxPdfContent_CalibratedCmykColorSpace`                                                    |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfColorSpace

| [Class] `TPdfColorSpace` → ` TPtxPdfContent_ColorSpace`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfColorSpaceGetComponents` → `PtxPdfContent_ColorSpace_GetComponentCount`.Renamed related functions `PdfColorSpace...` → `PtxPdfContent_ColorSpace_...`Removed related function `PdfColorSpaceGetName`.New related function `TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_CreateProcessColorSpace(``TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_ProcessColorSpaceTypeiType)`New related function  `TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_Copy(` `TPtxPdf_Document* pTargetDocument,` `TPtxPdfContent_ColorSpaceiColorSpace)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfColorSpaceType

| [Enum.] `TPdfColorSpaceType` → ` TPdfContent_ColorSpaceType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| This enum now reflects the class hierarchy of classes derived from `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes).Removed enum value `ePdfColorSpaceDeviceN`.Renamed enum values:`ePdfColorSpaceDeviceGray` → `ePtxPdfContent_ColorSpaceType_DeviceGrayColorSpace``ePdfColorSpaceDeviceRGB` → `ePtxPdfContent_ColorSpaceType_DeviceRgbColorSpace``ePdfColorSpaceDeviceCMYK` → `ePtxPdfContent_ColorSpaceType_DeviceCmykColorSpace``ePdfColorSpaceCalGray` → `ePtxPdfContent_ColorSpaceType_CalibratedGrayColorSpace``ePdfColorSpaceCalRGB` → `ePtxPdfContent_ColorSpaceType_CalibratedRgbColorSpace``ePdfColorSpaceLab` → `ePtxPdfContent_ColorSpaceType_LabColorSpace``ePdfColorSpaceICCBased` → `ePtxPdfContent_ColorSpaceType_IccBasedColorSpace``ePdfColorSpaceIndexed` → `ePtxPdfContent_ColorSpaceType_IndexedColorSpace``ePdfColorSpaceSeparation` → `ePtxPdfContent_ColorSpaceType_SeparationColorSpace``ePdfColorSpaceNChannel` → `ePtxPdfContent_ColorSpaceType_NChannelColorSpace`New enum value `ePtxPdfContent_ColorSpaceType_ColorSpace` |

#### TPdfContent

| [Class] `TPdfContent` → ` TPtxPdfContent_Content` |
| ------------------------------------------------- |

#### TPdfContentElement

| [Class] `TPdfContentElement` → ` TPtxPdfContent_ContentElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `TPdfTransformation* PdfContentElementGetTransform(``TPdfContentElement*)` → `BOOL PtxPdfContent_ContentElement_GetTransform(`  `TPtxPdfContent_ContentElement*,` `TPtxGeomReal_AffineTransform* pTransform)`SeeElements changed to class or struct.New related function `TPtxPdfContent_Contentelement* PtxPdfContent_ContentElement_Copy(` `TPtxPdf_Document *pTargetDocument,` `TPtxPdfContent_ContentElement* pContentElement)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPdfContentElementType

| [Enum.] `TPdfContentElementType` → ` TPtxPdfContent_ContentElementType`                   |
| ----------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfContentElementType...` → `ePtxPdfContent_ContentElementType_...` |

#### TPdfContentExtractor

| [Class] `TPdfContentExtractor` → ` TPtxPdfContent_ContentExtractor`                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfNewContentExtractor` → `PtxPdfContent_ContentExtractor_New`. See Constructors.Renamed remaining related functions `PdfContentExtractor...` → `PtxPdfContent_ContentExtractor_...` |

#### TPdfContentGenerator

| [Class] `TPdfContentGenerator` → ` TPtxPdfContent_ContentGenerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `BOOL PdfContentGeneratorPaintPath(` `TPdfContentGenerator*,` `TPdfPath* pPath,` `TPdfPaint* pFill,` `TPdfStrokeParams* pStroke,` `BOOL bIntersectClipping)` →  `BOOL PtxPdfContent_ContentGenerator_PaintPath(` `TPtxPdfContent_ContentGenerator*,` `TPtxPdfContent_Path* pPath,``TPtxPdfContent_Fill* pFill,``TPtxPdfContent_Stroke* pStroke)` See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).Changed behavior of related functions `PdfContentGeneratorPaintImage` → `PtxPdfContent_ContentGenerator_PaintImage` and `PdfContentGeneratorPaintImageMask` → `PtxPdfContent_ContentGenerator_PaintImageMask`: Value `NULL` for third argument of type `TPdfRectangle*` → `TPtxGeomReal_Rectangle*` is not supported anymore.Renamed related function `PdfNewContentGenerator` → `PtxPdfContent_ContentGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfContentGenerator...` → `PtxPdfContent_ContentGenerator_...`New related function `BOOL PtxPdfContent_ContentGenerator_ClipWithPath(``TPtxPdfContent_ContentGenerator*,``TPtxPdfContent_Path* pPath,``TPtxPdfContent_InsideRuleiInsideRule)`See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).New related function`BOOL PtxPdfContent_ContentGenerator_ClipWithText(``TPtxPdfContent_ContentGenerator*,``TPtxPdfContent_Text* pText)`See [Path and text clipping operations](C-interface.mdx#path-and-text-clipping-operations).New related function`BOOL PtxPdfContent_ContentGenerator_Close(``TPtxPdfContent_ContentGenerator*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing). |

#### TPdfDeviceColorSpaceType

| [Enum.] `TPdfDeviceColorSpaceType` → ` TPtxPdfContent_ProcessColorSpaceType`                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed enum value `ePdfDeviceColorSpaceTypeRGB` → `ePtxPdfContent_ProcessColorSpaceType_Rgb`.Renamed enum value `ePdfDeviceColorSpaceTypeCMYK` → `ePtxPdfContent_ProcessColorSpaceType_Cmyk`.Renamed remaining enum values `ePdfDeviceColorSpaceType...` → `ePtxPdfContent_ProcessColorSpaceType_...` |

#### TPtxPdfContent_DeviceGrayColorSpace

| [Class] `TPtxPdfContent_DeviceGrayColorSpace`                                                        |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPtxPdfContent_DeviceCmykColorSpace

| [Class] `TPtxPdfContent_DeviceCmykColorSpace`                                                        |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPtxPdfContent_DeviceRgbColorSpace

| [Class] `TPtxPdfContent_DeviceRgbColorSpace`                                                         |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfFillParams

| [Struct → class] `TPdfFillParams` → ` TPtxPdfContent_Fill`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct”to“class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Fill* PtxPdfContent_Fill_New(` `TPtxPdfContent_Paint* pPaint)`.See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Constructors](C-interface.mdx#constructors).New related functions `TPtxPdfContent_Fill PtxPdfContent_Fill_GetPaint(``TPtxPdfContent_Fill*)` `BOOL PtxPdfContent_Fill_SetPaint(` `TPtxPdfContent_Fill*,``TPtxPdfContent_FillpPaint)`.New related functions `TPtxPdfContent_Fill PtxPdfContent_Fill_GetInsideRule(` TPtxPdfContent_Fill*)``BOOL PtxPdfContent_Fill_SetInsideRule(` `TPtxPdfContent_Fill*,``TPtxPdfContent_FilliInsideRule)`. See [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path). See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |

#### TPdfFont

| [Class] `TPdfFont` → ` TPtxPdfContent_Font`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfFontGetCharWidth` → `PtxPdfContent_Font_GetCharacterWidth`.Renamed remaining related functions `PdfFont...` → `PtxPdfContent_Font_...`New related function `TPtxPdfContent_Font* PtxPdfContent_Font_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pStream,` `BOOL bEmbedded)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Font* PtxPdfContent_Font_CreateFromSystem(` `TPtxPdf_Document* pTargetDocument,` `const char* szFamily,` `const char* szStyle,` `BOOL bEmbedded)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

#### TPdfGroup

| [Class] `TPdfGroup` → ` TPtxPdfContent_Group`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGroup...` → `PtxPdfContent_Group_...`New related function`TPtxPdfContent_Group* PtxPdfContent_Group_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Size* pSize)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `TPtxPdfContent_Group* PtxPdfContent_Group_CreateFromPage(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``TPtxPdf_PageCopyOptions* pCopyOptions)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPdfGroupElement

| [Class] `TPdfGroupElement` → ` TPtxPdfContent_GroupElement`                                                                                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGroupElement...` → `PtxPdfContent_GroupElement_...`New related function`TPtxPdfContent_GroupElement* PtxPdfContent_GroupElement_CopyWithoutContent(``TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_GroupElement* pGroupElement)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

See [TPdfContentElement](#tpdfcontentelement) for inherited changes.

#### TPtxPdfContent_IccBasedColorSpace

| [Class] `TPtxPdfContent_IccBasedColorSpace`                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. Related function `TPtxPdfContent_IccBasedColorSpace* PtxPdfContent_IccBasedColorSpace_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pProfile)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfImage

| [Class] `TPdfImage` → ` TPtxPdfContent_Image`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfImageGetWidth`. Replaced by new related function `PtxPdfContent_Image_GetSize`.Removed related function `PdfImageGetHeight`. Replaced by new related function `PtxPdfContent_Image_GetSize`.Renamed remaining related functions `PdfImage...` → `PtxPdfContent_Image_...`New related function `TPtxPdfContent_Image* PtxPdfContent_Image_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor* pStream)`  See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `BOOL PtxPdfContent_Image_GetSize(` `TPtxPdfContent_Image*,``TPtxGeomReal_Size* pSize)`.See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size). |

#### TPdfImageElement

| [Class] `TPdfImageElement` → ` TPtxPdfContent_ImageElement`                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfImageElement...` → `PtxPdfContent_ImageElement_...`See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |

#### TPdfImageMask

| [Class] `TPdfImageMask` → ` TPtxPdfContent_ImageMask`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfImageMaskGetWidth`. Replaced by new related function `PtxPdfContent_ImageMask_GetSize`.Removed related function `PdfImageMaskGetHeight`. Replaced by new related function `PtxPdfContent_ImageMask_GetSize`.New related function `TPtxPdfContent_ImageMask* PtxPdfContent_ImageMask_Create(``TPtxPdf_Document* pTargetDocument,``TPtxSys_StreamDescriptor*pStream)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related function `BOOL PtxPdfContent_ImageMask_GetSize(``TPtxPdfContent_ImageMask*,``TPtxGeomReal_Size* pSize)`. See [Image size and image mask size](C-interface.mdx#image-size-and-image-mask-size).  |

#### TPdfImageMaskElement

| [Class] `TPdfImageMaskElement` → ` TPtxPdfContent_ImageMaskElement`                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfImageMaskElement...` → `PtxPdfContent_ImageMaskElement_...`See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |

#### TPtxPdfContent_IndexedColorSpace

| [Class] `TPtxPdfContent_IndexedColorSpace` |
| ------------------------------------------ |

| Extends `TPtxPdfContent_ColorSpace`.See [Color space classes](./C-interface.mdx#color-space-classes).

#### TPdfInsideRule

| [Enum.] `TPdfInsideRule` → ` TPtxPdfContent_InsideRule1                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfRuleNonzeroWindingNumber` → `ePdfContent_InsideRule_NonzeroWindingNumber``ePdfRuleEvenOdd` → `ePdfContent_InsideRule_EvenOdd` |

#### TPtxPdfContent_LabColorSpace

| [Class] `TPtxPdfContent_LabColorSpace`                                                               |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfLineCapStyle

| [Enum.] `TPdfLineCapStyle` → `TPtxPdfContent_LineCapStyle`        |
| ----------------------------------------------------------------- |
| Renamed enum values`ePdfCap...`→`ePtxPdfContent*LineCapStyle*...` |

#### TPdfLineJoinStyle

| [Enum.] `TPdfLineJoinStyle` → `TPtxPdfContent_LineJoinStyle`        |
| ------------------------------------------------------------------- |
| Renamed enum values`ePdfJoin...`→`ePtxPdfContent*LineJoinStyle*...` |

#### TPtxPdfContent_NChannelColorSpace

| [Class] `TPtxPdfContent_NChannelColorSpace`                                                          |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfPaint

| [Class] `TPdfPaint` → ` TPtxPdfContent_Paint`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfPaint...` → `PtxPdfContent_Paint_...`Changed related function `BOOL PdfPaintGetTransparency(``TPdfPaint*,``TPdfTransparencyParams* pTransparency)` → `TPtxPdfContent_Transparency* PtxPdfContent_Paint_GetTransparency(``TPtxPdfContent_Paint*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Paint* PtxPdfContent_Paint_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdfContent_ColorSpace* pColorSpace,``const double* pColor,``size_tnColors,``TPtxPdfContent_Transparency* pTransparency)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Unified paint creation](./C-interface.mdx#unified-paint-creation). |

#### TPdfPath

| [Class] `TPdfPath` → `TPtxPdfContent_Path`                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed related function `TPdfPath* PdfNewPath(TPdfFillRuleiRule)` → `TPtxPdfContent_Path* PtxPdfContent_Path_New()`. See [Constructors](C-interface.mdx#constructors) and [Separate inside rule from path](./C-interface.mdx#separate-inside-rule-from-path).Renamed related functions `PdfPath...` → `PtxPdfContent_Path_...` |

#### TPdfPathElement

| [Class] `TPdfPathElement` → ` TPtxPdfContent_PathElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfPathElement...` → `PtxPdfContent_PathElement_...`Changed related function  `BOOL PdfPathElementGetFill(` `TPdfPathElement*,` `TPdfFillParams*pFill)` → `TPtxPdfContent_Fill* PtxPdfContent_PathElement_GetFill(``TPtxPdfContent_PathElement*)`See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfPathElementGetStroke(``TPdfPathElement*,``TPdfStrokeParams* pStroke)` → `TPtxPdfContent_Stroke* PtxPdfContent_PathElement_GetStroke(``TPtxPdfContent_PathElement*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |

#### TPdfPathGenerator

| [Class] `TPdfPathGenerator` → ` TPtxPdfContent_PathGenerator`                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfNewPathGenerator` → `PtxPdfContent_PathGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfPathGenerator...` → `PtxPdfContent_PathGenerator_...`  |

#### TPtxPdfContent_SeparationColorSpace

| [Class] `TPtxPdfContent_SeparationColorSpace`                                                        |
| ---------------------------------------------------------------------------------------------------- |
| Extends `TPtxPdfContent_ColorSpace`. See [Color space classes](./C-interface.mdx#color-space-classes). |

#### TPdfShadingElement

| [Class]`TPdfShadingElement` → ` TPtxPdfContent_ShadingElement`       |
| -------------------------------------------------------------------- |
| See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |

#### TPdfStrokeParams

| [Struct → class] `TPdfStrokeParams` → ` TPtxPdfContent_Stroke`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct” to “class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function  `TPtxPdfContent_Stroke* PtxPdfContent_Stroke_New(` `TPtxPdfContent_Paint* pPaint,` `double dLineWidth)`. See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods) and [Constructors](C-interface.mdx#constructors).New related functions`TPtxPdfContent_Paint* PtxPdfContent_Stroke_GetPaint(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetPaint(``TPtxPdfContent_Stroke*,``TPtxPdfContent_Paint* pPaint)`.New related functions`double PtxPdfContent_Stroke_GetLineWidth(` `TPtxPdfContent_Stroke*)` `BOOL PtxPdfContent_Stroke_SetLineWidth(``TPtxPdfContent_Stroke*,` `double dLineWidth)`.New related functions `TPtxPdfContent_LineCapStyle PtxPdfContent_Stroke_GetLineCapStyle(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetLineCapStyle(``TPtxPdfContent_Stroke*,` `TPtxPdfContent_LineCapStyle iLineCapStyle)`.New related functions`TPtxPdfContent_LineJoinStyle PtxPdfContent_Stroke_GetLineJoinStyle(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetLineJoinStyle(``TPtxPdfContent_Stroke*,``TPtxPdfContent_LineJoinStyle iLineJoinStyle)`.New related functions `double PtxPdfContent_Stroke_GetMiterLimit(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetMiterLimit(``TPtxPdfContent_Stroke*,` `double dMiterLimit)`.New related functions `size_t PtxPdfContent_Stroke_GetDashArray(` `TPtxPdfContent_Stroke*,` `double* pBuffer,` `size_t nBufferSize)``BOOL PtxPdfContent_Stroke_SetDashArray(``TPtxPdfContent_Stroke*,` `const double* pBuffer,``size_t nBufferSize)`.New related functions `double PtxPdfContent_Stroke_GetDashPhase(``TPtxPdfContent_Stroke*)``BOOL PtxPdfContent_Stroke_SetDashPhase(``TPtxPdfContent_Stroke*,``double dDashPhase)`. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |

#### TPdfText

| [Class] `TPdfText` → ` TPtxPdfContent_Text`                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfText...` → `PtxPdfContent_Text_...`New related function `TPtxPdfContent_Text* PtxPdfContent_Text_Create(` `TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPdfTextElement

| [Class] `TPdfTextElement` → `TPtxPdfContent_TextElement`                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions`PdfTextElement...`→`PtxPdfContent*TextElement*...` See [TPdfContentElement](#tpdfcontentelement) for inherited changes. |

#### TPdfTextFragment

| [Class] `TPdfTextFragment` → ` TPtxPdfContent_TextFragment`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfTextFragmentGetUnicodeString` → `PtxPdfContent_TextFragment_GetText`.Changed related function `TPdfTransformation* PdfTextFragmentGetTransform(TPdfTextFragment*)` → `BOOL PtxPdfContent_TextFragment_GetTransform(``TPtxPdfContent_TextFragment*,``TPtxGeomReal_AffineTransform* pTransform)`  See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfTextFragmentGetFill(` `TPdfTextFragment*,``TPdfFillParams* pFill)` → `TPtxPdfContent_Fill* PtxPdfContent_TextFragment_GetFill(` `TPtxPdfContent_TextFragment*)` See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Changed related function `BOOL PdfTextFragmentGetStroke(` `TPdfTextFragment*,` `TPdfStrokeParams*pStroke)` → `TPtxPdfContent_Stroke*` `PtxPdfContent_TextFragment_GetStroke(` `TPtxPdfContent_TextFragment*)`See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).Renamed remaining related functions `PdfTextFragment...` → `PtxPdfContent_TextFragment_...`  |

#### TPdfTextGenerator

| [Class] `TPdfTextGenerator` → `TPtxPdfContent_TextGenerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed related function `PdfTextGeneratorSetRendering`. Replaced by related functions `PtxPdfContent_TextGenerator_SetFill` and `PtxPdfContent_TextGenerator_SetStroke`. See [Text generator](C-interface.mdx#text-generator).Renamed related function `PdfNewTextGenerator` → `PtxPdfContent_TextGenerator_New`. See [Constructors](C-interface.mdx#constructors).Renamed related function `PdfTextGeneratorSetCharSpacing` → `PtxPdfContent_TextGenerator_SetCharacterSpacing`. See [Renaming](C-interface.mdx#renaming).Renamed remaining related functions `PdfTextGenerator...` → `PtxPdfContent_TextGenerator_...`New related functions `TPtxPdfContent_Paint* PtxPdfContent_TextGenerator_GetFill(``TPtxPdfContent_TextGenerator*)``BOOL PtxPdfContent_TextGenerator_SetFill(``TPtxPdfContent_TextGenerator*,``TPtxPdfContent_Paint*pFill)`.New related functions `TPtxPdfContent_Stroke* PtxPdfContent_TextGenerator_GetStroke(``TPtxPdfContent_TextGenerator*)``BOOL PtxPdfContent_TextGenerator_SetStroke(``TPtxPdfContent_TextGenerator*,``TPtxPdfContent_Stroke* pStroke)`.New related function `BOOL PtxPdfContent_TextGenerator_Close(``TPtxPdfContent_TextGenerator*)`See [Closing and releasing](./C-interface.mdx#closing-and-releasing).  |

#### TPdfTransparencyParams

| [Struct → Class] `TPdfTransparencyParams` → ` TPtxPdfContent_Transparency`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from “struct” to “class”. See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct).New related function `TPtxPdfContent_Transparency* PtxPdfContent_Transparency_New(doubledAlpha)`.New related functions `TPtxPdfContent_BlendMode PtxPdfContent_Transparency_GetBlendMode(``TPtxPdfContent_Transparency*)``BOOL PtxPdfContent_Transparency_SetBlendMode(``TPtxPdfContent_Transparency*,``TPtxPdfContent_BlendModeiBlendMode)`.New related functions `double PtxPdfContent_Transparency_GetAlpha(``TPtxPdfContent_Transparency*)``BOOL PtxPdfContent_Transparency_SetAlpha(``TPtxPdfContent_Transparency*,``double dAlpha)`.See [Elements changed to class or struct](C-interface.mdx#elements-changed-to-class-or-struct). |

#### TPdfUngroupingSet

| [Enum.] `TPdfUngroupingSet` → ` TPtxPdfContent_UngroupingSelection`                                      |
| -------------------------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfUngroupingSet...` → `ePtxPdfContent_UngroupingSelection_...`  |

### Prefix PtxPdfForms

#### TPdfCheckBoxField

| [Class] `TPdfCheckBoxField` → ` TPtxPdfForms_CheckBox`                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfCheckBoxField...` → `PtxPdfForms_CheckBox_...`New related function `TPtxPdfForms_CheckBox* PtxPdfForms_CheckBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

See `TPdfFormField` for inherited changes.

#### TPdfChoiceField

| [Class] `TPdfChoiceField` → ` TPtxPdfForms_ChoiceField`                                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfChoiceField...` → `PtxPdfForms_ChoiceField_...` See [TPdfFormField](#tpdfformfield) for inherited changes. |

#### TPdfChoiceFieldType

| [Enum.] `TPdfChoiceFieldType` → ` TPtxPdfForms_ChoiceFieldType`                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfChoiceFieldTypeComboBoxField` → `ePtxPdfForms_ChoiceFieldType_ComboBox``ePdfChoiceFieldTypeListBoxField` → `ePtxPdfForms_ChoiceFieldType_ListBox`Renamed enum values `ePdfChoiceFieldType...` → `ePtxPdfForms_ChoiceFieldType_...` |

#### TPdfChoiceItem

| [Class] `TPdfChoiceItem` → ` TPtxPdfForms_ChoiceItem`                       |
| --------------------------------------------------------------------------- |
| Renamed related functions `PdfChoiceItem...` → `PtxPdfForms_ChoiceItem_...` |

#### TPdfChoiceItemList

| [Class] `TPdfChoiceItemList` → ` TPtxPdfForms_ChoiceItemList`                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfChoiceItemListAppend` → `PtxPdfForms_ChoiceItemList_Add`.Renamed remaining related functions `PdfChoiceItemList...` → `PtxPdfForms_ChoiceItemList_...` |

#### TPdfComboBoxField

| [Class] `TPdfComboBoxField` → ` TPtxPdfForms_ComboBox`                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfComboBoxField...` → `PtxPdfForms_ComboBox_...`>New related function `TPtxPdfForms_ComboBox* PtxPdfForms_ComboBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfChoiceField](#tpdfchoicefield) for inherited changes. |

#### TPdfCombTextField

| [Class] `TPdfCombTextField` → ` TPtxPdfForms_CombTextField` |
| ----------------------------------------------------------- |

| Renamed related functions `PdfCombTextField...` → `PtxPdfForms_CombTextField_...` New related function `TPtxPdfForms_CombTextField* PtxPdfForms_CombTextField_Create(``TPtxPdf_Document* pTargetDocument,``intiMaxLength)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).New related functions `int PtxPdfForms_CombTextField_GetMaxLength(``TPtxPdfForms_CombTextField*)``BOOL PtxPdfForms_CombTextField_SetMaxLength(``TPtxPdfForms_CombTextField*,``int iMaxLength)`. See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields). See [TPdfTextField](#tpdftextfield) for inherited changes.

#### TPdfFormField

| [Class] `TPdfFormField` → ` TPtxPdfForms_Field`                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfFormField...` → `PtxPdfForms_Field_...`See [TPdfFormFieldNode](#tpdfformfield) for inherited changes. |

#### TPtxPdfForms_FormFieldCopyStrategy

| [Enum.] `TPtxPdfForms_FormFieldCopyStrategy`                                                                                                                                                                                                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`ePtxPdfForms_FormFieldCopyStrategy_Copy``ePtxPdfForms_FormFieldCopyStrategy_Flatten``ePtxPdfForms_FormFieldCopyStrategy_Remove``ePtxPdfForms_FormFieldCopyStrategy_Copy AndUpdateWidgets`Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |

#### TPdfFormFieldType

| [Enum.] `TPdfFormFieldType` → ` TPtxPdfForms_FieldType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfFormFieldTypeCheckBoxField` → `ePtxPdfForms_FieldType_CheckBox``ePdfFormFieldTypeComboBoxField` → `ePtxPdfForms_FieldType_ComboBox``ePdfFormFieldTypeFormField` → `ePtxPdfForms_FieldType_Field``ePdfFormFieldTypeListBoxField` → `ePtxPdfForms_FieldType_ListBox``ePdfFormFieldTypePushButtonField` → `ePtxPdfForms_FieldType_PushButton``ePdfFormFieldTypeRadioButtonField` → `ePtxPdfForms_FieldType_RadioButtonGroup`Renamed enum values `ePdfFormFieldType...` → `ePtxPdfForms_FieldType_...` |

#### TPdfFormFieldNode

| [Class] `TPdfFormFieldNode` → ` TPtxPdfForms_FieldNode`                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfFormFieldNode...` → `PtxPdfForms_FieldNode_...`New related function `TPtxPdfForms_FieldNode* PtxPdfForms_FieldNode_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfForms_FieldNode* pFieldNode)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). |

#### TPdfFormFieldNodeMap

| [Class] `TPdfFormFieldNodeMap` → ` TPtxPdfForms_FieldNodeMap`                       |
| ----------------------------------------------------------------------------------- |
| Renamed related functions `PdfFormFieldNodeMap...` → `PtxPdfForms_FieldNodeMap_...` |

#### TPdfFormFieldNodeType

| [Enum.] `TPdfFormFieldNodeType` → ` TPtxPdfForms_FieldNodeType`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum values:`ePdfFormFieldNodeTypeCheckBoxField` → `ePtxPdfForms_FieldNodeType_CheckBox``ePdfFormFieldNodeTypeComboBoxField` → `ePtxPdfForms_FieldNodeType_ComboBox``ePdfFormFieldNodeTypeFormField` → `ePtxPdfForms_FieldNodeType_Field``ePdfFormFieldNodeTypeFormFieldNode` → `ePtxPdfForms_FieldNodeType_FieldNode``ePdfFormFieldNodeTypeListBoxField` → `ePtxPdfForms_FieldNodeType_ListBox``ePdfFormFieldNodeTypePushButtonField` → `ePtxPdfForms_FieldNodeType_PushButton``ePdfFormFieldNodeTypeRadioButtonField` → `ePtxPdfForms_FieldNodeType_RadioButtonGroup`Renamed enum values `ePdfFormFieldNodeType...` → `ePtxPdfForms_FieldNodeType_...` |

#### TPdfGeneralTextField

| [Class] `TPdfGeneralTextField` → ` TPtxPdfForms_GeneralTextField`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfGeneralTextField...` → `PtxPdfForms_GeneralTextField_...`New related function `TPtxPdfForms_GeneralTextField* PtxPdfForms_GeneralTextField_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). New related functions `BOOL PtxPdfForms_GeneralTextField_GetMaxLength(``TPtxPdfForms_GeneralTextField*,``int* pMaxLength)``BOOL PtxPdfForms_GeneralTextField_SetMaxLength(``TPtxPdfForms_GeneralTextField*,``const int*pMaxLength)`.See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields).  |

See [TPdfTextField](#tpdfcombtextfield) for inherited changes.

#### TPdfListBoxField

| [Class] `TPdfListBoxField` → ` TPtxPdfForms_ListBox`                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfListBoxField...` → `PtxPdfForms_ListBox_...`New related function `TPtxPdfForms_ListBox* PtxPdfForms_ListBox_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfChoiceField](#tpdfchoicefield) for inherited changes.

#### TPdfPushButtonField

| [Class] `TPdfPushButtonField` → ` TPtxPdfForms_PushButton` |
| ---------------------------------------------------------- |

#### TPdfRadioButton

| [Class] `TPdfRadioButton` → ` TPtxPdfForms_RadioButton`                       |
| ----------------------------------------------------------------------------- |
| Renamed related functions `PdfRadioButton...` → `PtxPdfForms_RadioButton_...` |

#### TPdfRadioButtonField

| [Class] `TPdfRadioButtonField` → ` TPtxPdfForms_RadioButtonGroup`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions `PdfRadioButtonFieldGetCanToggleOff` and `PdfRadioButtonFieldSetCanToggleOff`.>Renamed remaining related functions `PdfRadioButtonField...` → `PtxPdfForms_RadioButtonGroup_...`New related function `TPtxPdfForms_RadioButtonGroup* PtxPdfForms_RadioButtonGroup_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfFormField](#tpdfformfield) for inherited changes.  |

#### TPdfRadioButtonList

| [Class] `TPdfRadioButtonList` → ` TPtxPdfForms_RadioButtonList`                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfRadioButtonListAppend` → `PtxPdfForms_RadioButtonList_Add`.Renamed remaining related functions `PdfRadioButtonList...` → `PtxPdfForms_RadioButtonList_...` |

#### TPdfSignatureField

| [Class] `TPdfSignatureField` → ` TPtxPdfForms_SignatureField`                       |
| ----------------------------------------------------------------------------------- |
| Renamed related functions `PdfSignatureField...` → `PtxPdfForms_SignatureField_...` |

#### TPdfSignatureFieldList

| [Class] `TPdfSignatureFieldList` → ` TPtxPdfForms_SignatureFieldList`                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related function `PdfSignatureFieldListAppend` → `PtxPdfForms_SignatureFieldList_Add`.Renamed remaining related functions `PdfSignatureFieldList...` → `PtxPdfForms_SignatureFieldList_...` |

#### TPdfSubForm

| [Class] `TPdfSubForm` → ` TPtxPdfForms_SubForm`                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related functions `PdfSubForm...` → `PtxPdfForms_SubForm_...`New related function `TPtxPdfForms_SubForm* PtxPdfForms_SubForm_Create(``TPtxPdf_Document* pTargetDocument)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfFormFieldNode](#tpdfformfieldnode) for inherited changes.` |

#### TPdfTextField

| [Class] `TPdfTextField` → ` TPtxPdfForms_TextField`                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related functions `PdfTextFieldGetMaxLength` and `PdfTextFieldSetMaxLength`. See [MaxLength in text fields](./C-interface.mdx#maxlength-in-text-fields)Renamed related functions `PdfTextField...` → `PtxPdfForms_TextField_...` |

See [TPdfFormFieldNode](#tpdfformfieldnode) for inherited changes.

#### TPdfTextFieldType

| [Enum.] `TPdfTextFieldType` → ` TPtxPdfForms_TextFieldType`                   |
| ----------------------------------------------------------------------------- |
| Renamed enum values `ePdfTextFieldType...` → `ePtxPdfForms_TextFieldType_...` |

#### TPdfWidget

| [Class] `TPdfWidget` → ` TPtxPdfForms_Widget`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `TPdfAnnotation`. See [Annotations](C-interface.mdx#annotations).Duplicated related function `TPtxGeomReal_Rectangle* PtxPdfForms_Widget_GetBoundingBox(``TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfForms_Widget_GetHidden(` `TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfForms_Widget_GetNoPrint(``TPtxPdfForms_Widget*)`from former base class `TPdfAnnotation`. |

#### TPdfWidgetList

| [Class] `TPdfWidgetList` → ` TPtxPdfForms_WidgetList`                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfWidgetListAppend` → `PtxPdfForms_WidgetList_Add`.Renamed remaining related functions `PdfWidgetList...` → `PtxPdfForms_WidgetList_...` |

### Prefix PtxPdfNav

#### TPdfDestination

| [Class] `TPdfDestination` → ` TPtxPdfNav_Destination`                       |
| --------------------------------------------------------------------------- |
| Renamed related functions `PdfDestination...` → `PtxPdfNav_Destination_...` |

#### TPdfDestinationType

| [Enum.] `TPdfDestinationType` → ` TPtxPdfNav_DestinationType`                   |
| ------------------------------------------------------------------------------- |
| Renamed enum values `ePdfDestinationType...` → `ePtxPdfNav_DestinationType_...` |

#### TPdfDirectDestination

| [Class] `TPdfDirectDestination` → ` TPtxPdfNav_DirectDestination`                       |
| --------------------------------------------------------------------------------------- |
| Renamed related functions `PdfDirectDestination...` → `PtxPdfNav_DirectDestination_...` |

See [TPdfDestination](#tpdfdestination) for inherited changes.

#### TPdfDirectDestinationType

| [Enum.] `TPdfDirectDestinationType` → ` TPtxPdfNav_DirectDestinationType`                   |
| ------------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfDirectDestinationType...` → `ePtxPdfNav_DirectDestinationType_...` |

#### TPdfEmbeddedPdfLink

| [Class] `TPdfEmbeddedPdfLink` → ` TPtxPdfNav_EmbeddedPdfLink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewEmbeddedPdfLink`. See [Constructors](C-interface.mdx#constructors).Renamed related functions `PdfEmbeddedPdfLink...` → `PtxPdfNav_EmbeddedPdfLink_...`New related function `TPtxPdfNav_EmbeddedPdfLink* PtxPdfNav_EmbeddedPdfLink_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Rectangle* pBoundingBox,``TPtxPdf_FileReference* pFileReference)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfLink](#tpdflink) for inherited changes. |

#### TPdfFitHeightDestination

| [Class] `TPdfFitHeightDestination` → ` TPtxPdfNav_FitHeightDestination`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitHeightDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfFitHeightDestination...` → `PtxPdfNav_FitHeightDestination_...`New related function `TPtxPdfNav_FitHeightDestination* PtxPdfNav_FitHeightDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.  |

#### TPdfFitPageDestination

| [Class] `TPdfFitPageDestination` → ` TPtxPdfNav_FitPageDestination`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitPageDestination`. See [Constructors].Renamed remaining related functions `PdfFitPageDestination...` → `PtxPdfNav_FitPageDestination_...`New related function`TPtxPdfNav_FitPageDestination* PtxPdfNav_FitPageDestination_Create(``TPtxPdf_Document* pTargetDocument, ``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.

#### TPdfFitRectangleDestination

| [Class] `TPdfFitRectangleDestination` → ` TPtxPdfNav_FitRectangleDestination`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitRectangleDestination`. See [Constructors](C-interface.mdx#constructors). Renamed remaining related functions `PdfFitRectangleDestination...` → `PtxPdfNav_FitRectangleDestination_...`New related function `TPtxPdfNav_FitRectangleDestination* PtxPdfNav_FitRectangleDestination_Create(` `TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``TPtxGeomReal_Rectangle* pRectangle)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.

#### TPdfFitWidthDestination

| [Class] `TPdfFitWidthDestination` → ` TPtxPdfNav_FitWidthDestination`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewFitWidthDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfFitWidthDestination...` → `PtxPdfNav_FitWidthDestination_...`New related function `TPtxPdfNav_FitWidthDestination* PtxPdfNav_FitWidthDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``BOOL bFitActualContent)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.

#### TPdfInternalLink

| [Class] `TPdfInternalLink` → ` TPtxPdfNav_InternalLink`                        |
| ------------------------------------------------------------------------------ | ------------------------------------------------ |
| Renamed related functions `PdfInternalLink...` → `PtxPdfNav_InternalLink_... ` | See [TPdfLink](#tpdflink) for inherited changes. |

#### TPdfLink

| [Class] `TPdfLink` → ` TPtxPdfNav_Link`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from class `TPdfAnnotation`. See [Annotations](C-interface.mdx#annotations).Renamed related functions `PdfLink...` → `PtxPdfNav_Link_...`New related function `TPtxPdfNav_Link* PtxPdfNav_Link_Copy(` `TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_Link* pLink)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). Duplicated related function `TPtxGeomReal_Rectangle* PtxPdfNav_Link_GetBoundingBox(``TPtxPdfNav_Link*)` from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfNav_Link_GetHidden(``TPtxPdfNav_Link*)`from former base class `TPdfAnnotation`.Duplicated related function `BOOL PtxPdfNav_Link_GetNoPrint(``TPtxPdfNav_Link*)`from former base class `TPdfAnnotation`. |

#### TPtxPdfNav_LinkList

| [Class] `TPtxPdfNav_LinkList`                       |
| --------------------------------------------------- |
| A list that contains [TPdfLink](#tpdflink) objects. |

#### TPdfLinkType

| [Enum.] `TPdfLinkType` → ` TPtxPdfNav_LinkType`                   |
| ----------------------------------------------------------------- |
| Renamed enum values `ePdfLinkType...` → `ePtxPdfNav_LinkType_...` |

#### TPdfLocationZoomDestination

| [Class] `TPdfLocationZoomDestination` → ` TPtxPdfNav_LocationZoomDestination`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewLocationZoomDestination`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfLocationZoomDestination...` → `PtxPdfNav_LocationZoomDestination_...`New related function`TPtxPdfNav_ZoomDestination* PtxPdfNav_LocationZoomDestination_Create(``TPtxPdf_Document* pTargetDocument,``TPtxPdf_Page* pPage,``const double* pLeft,``const double* pTop,``const double* pZoom)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfDirectDestination](#tpdfdirectdestination) for inherited changes.

#### TPdfNamedDestination

| [Class] `TPdfNamedDestination` → ` TPtxPdfNav_NamedDestination`                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfNamedDestination...` → `PtxPdfNav_NamedDestination_...`New related function `TPtxPdfNav_NamedDestination* PtxPdfNav_NamedDestination_Create(``TPtxPdf_Document* pTargetDocument,``const char* szName,``TPtxPdfNav_DirectDestination* pTarget)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

See [TPdfDestination](#tpdfdestination) for inherited changes.

#### TPtxPdfNav_NamedDestinationCopyStrategy

| [Enum.] `TPtxPdfNav_NamedDestinationCopyStrategy`                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`ePtxPdfNav_NamedDestinationCopyStrategy_Copy``ePtxPdfNav_NamedDestinationCopyStrategy_Resolve`Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |

#### TPtxPdfNav_OutlineCopyOptions

| [Class] `TPtxPdfNav_OutlineCopyOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Related function `TPtxPdfNav_OutlineCopyOptions* PtxPdfNav_OutlineCopyOptions_New()`Related functions `TPtxPdfNav_NamedDestinationCopyStrategy PtxPdfNav_OutlineCopyOptions_GetNamedDestinations(``TPtxPdfNav_OutlineCopyOptions*)``BOOL PtxPdfNav_OutlineCopyOptions_SetNamedDestinations(``TPtxPdfNav_OutlineCopyOptions*,``TPtxPdfNav_NamedDestinationCopyStrategyiNamedDestinations)`Default: `ePtxPdfNav_NamedDestinationCopyStrategy_Copy`Related functions`BOOL PtxPdfNav_OutlineCopyOptions_GetCopyLogicalStructure(``TPtxPdfNav_OutlineCopyOptions*)``BOOL PtxPdfNav_OutlineCopyOptions_SetCopyLogicalStructure(``TPtxPdfNav_OutlineCopyOptions*,``BOOL bCopyLogicalStructure)`Default: `TRUE` Substitutes the removed `TPdfCopyOption`. See [Copy options](C-interface.mdx#copy-options). |

#### TPdfOutlineItem

| [Class] `TPdfOutlineItem` → ` TPtxPdfNav_OutlineItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New related function `TPtxPdfNav_OutlineItem* PtxPdfNav_OutlineItem_Create(` `TPtxPdf_Document* pTargetDocument,``const char* szTitle,` `TPtxPdfNav_Destination* pDestination)` See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). New related function`TPtxPdfNav_OutlineItem* PtxPdfNav_OutlineItem_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_OutlineItem* pOutlineItem,``TPtxPdfNav_OutlineCopyOptions* pOptions)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [Copy options](C-interface.mdx#copy-options). |

#### TPdfOutlineItemList

| [Class] `TPdfOutlineItemList` → ` TPtxPdfNav_OutlineItemList`                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed related function `PdfOutlineItemListAppend` → `PtxPdfNav_OutlineItemList_Add`.Renamed remaining related functions `PdfOutlineItemList...` → `PtxPdfNav_OutlineItemList_...`  |

#### TPdfPageDisplay

| [Struct] `TPdfPageDisplay` → ` TPtxPdfNav_PageDisplay`                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed default value of field `bContinuous` from `TRUE` to `FALSE`.Removed related function `PdfPageDisplayInitialize`. |

#### TPdfPageLayout

| [Enum.] `TPdfPageLayout` → ` TPtxPdfNav_PageLayout`                   |
| --------------------------------------------------------------------- |
| Renamed enum values `ePdfPageLayout...` → `ePtxPdfNav_PageLayout_...` |

#### TPdfViewerNavigationPane

| [Enum.] `TPdfViewerNavigationPane` → ` TPtxPdfNav_ViewerNavigationPane`                   |
| ----------------------------------------------------------------------------------------- |
| Renamed enum values `ePdfViewerNavigationPane...` → `ePtxPdfNav_ViewerNavigationPane_...` |

#### TPdfViewerSettings

| [Class] `TPdfViewerSettings` → ` TPtxPdfNav_ViewerSettings`                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Renamed related functions `PdfViewerSettings...` → `PtxPdfNav_ViewerSettings_...` New related function `TPtxPdfNav_ViewerSettings* PtxPdfNav_ViewerSettings_Copy(``TPtxPdf_Document* pTargetDocument,``TPtxPdfNav_ViewerSettings* pViewerSettings)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods).  |

#### TPdfWebLink

| [Class] `TPdfWebLink[` → ` TPtxPdfNav_WebLink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed related function `PdfNewWebLink`. See [Constructors](C-interface.mdx#constructors).Renamed remaining related functions `PdfWebLink...` → `PtxPdfNav_WebLink_...`New related function `TPtxPdfNav_WebLink* PtxPdfNav_WebLink_Create(``TPtxPdf_Document* pTargetDocument,``TPtxGeomReal_Rectangle* pBoundingBox,``const char* szUri)`See [Creation and copying methods](./C-interface.mdx#creation-and-copying-methods). See [TPdfLink](#tpdflink) for inherited changes. |

## Prefix PtxSys

| [Struct] `TPdfDate` → ` TPtxSys_Date`        |
| -------------------------------------------- |
| Removed offset of `1900` from field `iYear`. |

#### TPdfStreamDescriptor

| [Struct] `TPdfStreamDescriptor` → `TPtxSys_StreamDescriptor`                                  |
| --------------------------------------------------------------------------------------------- |
| Renamed related function `PdfCreateFILEStreamDescriptor` → `PtxSysCreateFILEStreamDescriptor` |

---

## .NET interface changes for PDF Toolbox SDK

There are several changes in naming and behavior in the .NET interface to bear in mind when migrating from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

:::note
This page provides the changes between the two products only. For full reference information on the PDF Toolbox SDK, see [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/dotnet/html/R_Project_API_Reference.htm).
:::

## Namespaces

The company namespace of PDF Tools AG is `PdfTools`, both in 3-Heights® PDF Toolbox API and in PDF Toolbox SDK. In 3-Heights®, most interface elements reside in the namespace `PdfTools.Pdf`, except for the following type,which reside directly in `PdfTools`:

- Point
- Rectangle
- Size
- ErrorCode
- ErrorCodeException

PDF Toolbox SDK introduces the following new namespaces:

| Namespace                                          | Area of usage               |
| -------------------------------------------------- | --------------------------- |
| `PdfTools.FourHeights.PdfToolbox`                  | Base namespace              |
| `PdfTools.FourHeights.PdfToolbox.Geometry`         | Geometric related           |
| `PdfTools.FourHeights.PdfToolbox.Geometry.Real`    | For floating point numbers  |
| `PdfTools.FourHeights.PdfToolbox.Geometry.Integer` | For integer numbers         |
| `PdfTools.FourHeights.PdfToolbox.Pdf`              | General PDF related         |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations`  | Annotation related          |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Content`      | Page content related        |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Forms`        | Form field related          |
| `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation`   | Document navigation related |

## The Sdk class

#### License keys and product version

In 3-Heights®, the public properties `LicenseKey` and `ProductVersion` of the common base class `Internal.NativeObject` allows setting a license key and querying the version of the API.

In PDF Toolbox SDK, this functionality has been moved to the class `Sdk`. Specifically:

- `Sdk.Initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Sdk.Version` gets the API’s version number as a string.

#### The PDF Producer entry

In 3-Heights® PDF Toolbox API, when creating a PDF, the `Metadata` object sets the PDF’s Producer entry via the property `Metadata.Producer`.

In PDF Toolbox SDK, the class `Pdf.Metadata` has no setter for the `Producer` property. Instead, the `Producer` entry for all output PDFs is preconfigured as a string consisting of two parts:

1. The first part (the “base” part) is encodesd in the license key. Hence, this part is determined when buying a licensefrom Pdftools.
2. The second part (the “suffix” part) is configured when calling `Sdk.Initialize` as an argument. It is recommended to use the suffix solely for version information. The assembled “Producer” entry can be obtained after calling `Sdk.Initialize` using the property `Sdk.ProducerFullName`.

## Removal of IDisposable implementation

In PDF Toolbox SDK, the implementation of the [IDisposable interface](../sdk-dotnet.mdx#idisposable-objects) has been removed from all but the following classes:

- `Document`
- `ContentGenerator`
- `TextGenerator`

Native resources are now released automatically when getting or appending a page.

## Value types

In 3-Heights® PDF Toolbox API, interface elements documented as “struct” are actually classes (class), i.e. reference types.

In PDF Toolbox SDK, interface elements documented as “struct” are value types (struct). This affects the following existing interface elements:

- `Point`
- `Size`
- `Rectangle`
- `Transformation`
- `PageDisplay`

and following new interface element:
`Geometry.Integer.Size`

As a consequence, the above types don’t have a constructor and all fields are default constructed. See also [Affine transform objects should be initialized](#affine-transform-objects-should-be-initialized).

## Exceptions

In PDF Toolbox SDK, the `ErrorCodeException` has been renamed to `PdfToolboxException`. The property `ErrorCodeException.Code` has been removed and substituted by the following new classes, each extending `PdfToolboxException`:

- `ConformanceException`
- `CorruptException`
- `LicenseException`
- `PasswordException`
- `UnknownFormatException`
- `UnsupportedFeatureException`

Instead of an `ErrorCodeException` with property `ErrorCodeException.ErrorCodeErrorCode.IO`, a `System.IO.IOException` is generated.

## Renaming

Some interface elements have been renamed. The following principles apply:

- Interface elements that include abbreviations are now written consistently in Pascal case. For example `RGB` → is now `Rgb`, except for two-letter abbreviations, which are written as two capital letters, such as`IO`.
- Some abbreviations have been changed to full words, for example `Char` → `Character`.
- Some words that are repeated in the introduced namespace have been dropped. For example, `AnnotationPopup` → is now `Pdf.Annotations.Popup`.
- Improved clarity, brevity, jargon, and technical correctness.

## Affine transform objects should be initialized

In 3-Heights® PDF Toolbox API, `Transformation` is a class.

In PDF Toolbox SDK, this element has been renamed to `Geometry.Real.AffineTransformation`, and its type has changed to struct (See [Value types](#value-types)).
Specifically, default constructed `Geometry.Real.AffineTransform` objects are not valid. (A matrix with all values 0 is singular.) Default constructed `Geometry.Real.AffineTransform` objects should always be initialized with `Geometry.Real.AffineTransform.Identity`. For example:

```
AffineTransform transform = AffineTransform.Identity;
```

## Creation and copying methods

In 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by static methods `Document.Create...` and copied from an input document to an output document by static methods `Document.Copy...`, e.g. `Document.CreatePage`, `Document.CopyPage`.

In PDF Toolbox SDK, all these methods have been moved from the `Document` class to the class that is created or copied. For example, method `Document.CreatePage` → `Pdf.Page.Create`.

This affects the following classes:

- `Page`
- `Image`
- `ImageMask`
- `Font`
- `Group`
- `ColorSpace`
- `Paint`
- `Text`
- `Metadata`
- `FileReference`
- `SubForm`
- `GeneralTextField`
- `CombTextField`
- `CheckBoxField`
- `RadioButtonField`
- `ListBoxField`
- `ComboBoxField`
- `NamedDestination`
- `OutlineItem`
- `Annotation`
- `Link`
- `FileAttachmentAnnotation`
- `FreeTextAnnotation`
- `StickyNoteAnnotation`
- `TextStampAnnotation`
- `CustomStampAnnotation`
- `CircleAnnotation`
- `SquareAnnotation`
- `LineAnnotation`
- `PolyLineAnnotation`
- `PolygonAnnotation`
- `FreeDrawingAnnotation`
- `ContentElement`
- `FormFieldNode`

## Constructors

In 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. E.g. `FitPageDestination.FitPageDestination`.

In PDF Toolbox SDK, most of these document-associated objects are now created and copied with static methods `Create` and `Copy`.

This affects the following classes:

- `EmbeddedPdfLink`
- `FitHeightDestination`
- `FitPageDestination`
- `FitRectangleDestination`
- `FitWidthDestination`
- `LocationZoomDestination`
- `WebLink`

In PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:

- `Pdf.Encryption`
- `Pdf.Content.ContentExtractor`
- `Pdf.Content.ContentGenerator`
- `Pdf.Content.Fill`
- `Pdf.Content.PageCopyOptions`
- `Pdf.Content.PathGenerator`
- `Pdf.Content.Path`
- `Pdf.Content.Stroke`
- `Pdf.Content.TextGenerator`
- `Pdf.Content.Transparency`
- `Pdf.Navigation.OutlineCopyOptions`

## Unknown PDF conformance

In 3-Heights® PDF Toolbox API, the `Conformance` enumeration has a value `Conformance.Unknown`.

The PDF Toolbox SDK enum `Pdf.Conformance` has no such value. The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:

- In the method `Pdf.Document.Create`, the type of the second argument has changed from `ConformancetoPdf.Conformance?`, where a `null` value has the same meaning as the removed value `Conformance.Unknown`.
- The property `Pdf.Document.Conformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating or (if created with `null`) the conformance the output PDF would have if closed now.

## Copy options

In 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `CopyOption` enum.

In PDF Toolbox SDK, this enum has been substituted by new classes:

- `Pdf.PageCopyOptionsUsed` in methods `Pdf.Page.CopyandPdf.Group.CreateFromPage`.
- `Pdf.Navigation.OutlineCopyOptionsUsed` in method `Pdf.Navigation.OutlineItem.Copy`.

Each copying configuration decision is reflected in a class member. Apart from Boolean for on-off decisions, the following enumerations model possible choices:

- `Pdf.CopyStrategy`
- `Pdf.RemovalStrategy`
- `Pdf.NameConflictResolution`
- `Pdf.Forms.FormFieldCopyStrategy`
- `Pdf.Navigation.NamedDestinationCopyStrategy`

This clarifies the copying behavior and allows sensible default values.

## Color space classes

**Class hierarchy**  
In 3-Heights® PDF Toolbox API, there is a single class `ColorSpace`, which covers all types of color spaces.

In PDF Toolbox SDK, the `ColorSpaceType` enumeration and the property `ColorSpace.Type` have been removed. Instead, there are the following new classes, all extending `Pdf.Content.ColorSpace`:

- `Pdf.Content.CalibratedGrayColorSpace`
- `Pdf.Content.CalibratedRgbColorSpace`
- `Pdf.Content.DeviceCmykColorSpace`
- `Pdf.Content.DeviceGrayColorSpace`
- `Pdf.Content.DeviceRgbColorSpace`
- `Pdf.Content.IccBasedColorSpace`
- `Pdf.Content.IndexedColorSpace`
- `Pdf.Content.LabColorSpace`
- `Pdf.Content.NChannelColorSpace`
- `Pdf.Content.SeparationColorSpace`

The 3-Heights® PDF Toolbox API color space type `DeviceN` now is subsumed by the more general `Pdf.Content.NChannelColorSpace`.

**Device color spaces versus process color spaces**  
In 3-Heights® PDF Toolbox API, the method `Document.CreateDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.

In PDF Toolbox SDK, the enumeration `DeviceColorSpaceType` has been renamed to `Pdf.Content.ProcessColorSpaceType`. The class `Pdf.Content.ColorSpace` now has the following static method:

```
Pdf.Content.ColorSpace CreateProcessColorSpace(Pdf.Document targetDocument, Pdf.Content.DeviceColorSpaceType type)
```

This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based (CMYK) color space.

## Embedded/Associated/Attached files

In 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `FileAttachmentAnnotation` are jointlylisted in the property `Document.EmbeddedFiles`.

In PDF Toolbox SDK, embedded files, associated files, and files contained in file attachment annotations are treated separately. A `Pdf.Document` now has two lists for appending:

- `Pdf.Document.AssociatedFiles`
- `Pdf.Document.PlainEmbeddedFiles`

The former property `Document.EmbeddedFiles` has been renamed to `Pdf.Document.AllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `Pdf.Annotations.FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane,. For example, the “Attachments” pane in the Adobe PDF viewer.

## Annotations

In PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:

- `FreeDrawingAnnotation` → `Pdf.Annotations.InkAnnotation`
- `CircleAnnotation`→ `Pdf.Annotations.EllipseAnnotation`
- `SquareAnnotation` → `Pdf.Annotations.RectangleAnnotation`

The property `RadioButtenField.CanToggleOff` has been removed. In most PDF viewers, there is no support for this feature.

**Class hierarchy**  
In 3-Heights® PDF Toolbox API, `WidgetandLink` extend the base class `Annotation`. In PDF Toolbox SDK, the classes `Pdf.Forms.Widget` and `Pdf.Navigation.Link` have been separated from their former base class. Due to this separation:
A `Pdf.Page` now has the following lists:

- `Pdf.Page.Annotations`
- `Pdf.Page.Links`
- `Pdf.Page.FormFieldWidgets`

The following properties of `Pdf.Annotations.Annotation` have been replicated in `Pdf.Forms.Widget` and `Pdf.Navigation.Link`:

- `BoundingBox`
- `Hidden`
- `NoPrint`
  The intermediate base classes `PolyDrawingAnnotation` and `ShapeDrawingAnnotation` have been removed.
  All drawing annotations now directly extend the class `Pdf.Annotations.DrawingAnnotation`.Those drawing annotations that have a closed path (`Pdf.Annotations.PolygonAnnotation`, `Pdf.Annotations.EllipseAnnotation`, `Pdf.Annotations.RectangleAnnotation`) have a property `Fill`.

**Class hierarchy comparison**

| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |

![.NET class hierarchy comparison diagram](/img/Toolbox_NET-class-comparison.png)

## MaxLength in text fields

In 3-Heights® PDF Toolbox API, the error behavior of the property `TextField.MaxLength` depends on the actual underlying class: `GeneralTextField` allows null values, while `CombTextField` does not.

In PDF Toolbox SDK, the property `TextField.MaxLength` has been removed and replicated in the derived classes `Pdf.Forms.CombTextField` and `Pdf.Forms.GeneralTextField`, in the latter as a nullable `int?`.

## Unified paint creation

In 3-Heights® PDF Toolbox API, there exist three methods for creating a `Paint` object:

- `Document.CreateSolidPaint`
- `Document.CreateAlphaPaint`
- `Document.CreateBlendingPaint`

In PDF Toolbox SDK, these methods have been replaced by a single static method` Pdf.Content.Paint.Create`. See also [Creation and copying methods](#creation-and-copying-methods).

## Separate inside rule from path

In 3-Heights® PDF Toolbox API, the constructor `Path.Path` has an argument `InsideRule rule`.

In PDF Toolbox SDK, this argument is dropped. Instead, the `InsideRule` now is specified in a new member of `Pdf.Content.Fill` when painting the path with `Pdf.Content.ContentGenerator.PaintPath`, or it is specified ina method argument when clipping with `Pdf.Content.ContentGenerator.ClipWithPath`. This removes ambiguity and allows a separated treatment of the inside rule for path filling and path clipping.

## Path and text clipping operations

In 3-Heights® PDF Toolbox API, the `ContentGenerator` supports simultaneous clipping and painting operations.

In PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:
The argument `bool intersectClipPath` has been removed from the method `ContentGenerator.PaintPath`.
The method `TextGenerator.SetRendering` has been removed (see also [Text generator](#text-generator)), and its argument `bool intersectClipping` has been dropped without a replacement.
The new class `Pdf.Content.ContentGenerator` has two new methods for path and text clipping operations:

- `Pdf.Content.ContentGenerator.ClipWithPath`
- `Pdf.Content.ContentGenerator.ClipWithText`

To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.

## Text generator

In PDF Toolbox SDK, the method `TextGenerator.SetRendering` has been substituted by two separate properties:

- `Pdf.Content.TextGenerator.Fill`
- `Pdf.Content.TextGenerator.Stroke`

## Image size and image mask size

In 3-Heights® PDF Toolbox API, `Image`and `ImageMask` have properties `Width` and `Height`.

In PDF Toolbox SDK, these are substituted by properties `Pdf.Content.Image.Size` and `Pdf.Content.ImageMask.Size`, both of which have the new type `Geometry.Integer.Size`.

---

## Reference

For all changes in the .NET interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see **[.NET Reference](dotnet-reference.mdx)**.

---

## Reference for changes in .NET interface

This section lists all changes in the .NET interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK namespace.

:::note
This page provides the changes between the two products only. For full reference information on the PDF Toolbox SDK, see [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/dotnet/html/R_Project_API_Reference.htm).
:::

| [Class]`PdfTools.internal.NativeObject` → `PdfTools.FourHeights.PdfToolbox.Internal.NativeObject`                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed members:Removed static property `LicenseKey`.Removed static method `CheckLicense`. Removed static property `ProductVersion`.The above have been substituted by new static members in `Sdk` |

## Base namespace

#### PdfTools.FourHeights.PdfToolbox.ConformanceException

| [Class] `PdfTools.FourHeights.PdfToolbox.ConformanceException`                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Conformance`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.FourHeights.PdfToolbox.CorruptException

| [Class] `PdfTools.FourHeights.PdfToolbox.CorruptException`                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Corrupt`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.ErrorCode

| [Enum.] `PdfTools.ErrorCode` → `PdfTools.FourHeights.PdfToolbox.ErrorCode` |
| -------------------------------------------------------------------------- |
| Removed. See [Exceptions](dotnet-interface.mdx#exceptions).                |

#### PdfTools.ErrorCodeException

| [Class] `PdfTools.ErrorCodeException` → `PdfTools.FourHeights.PdfToolbox.PdfToolboxException`                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed property `Code`.In all affected methods and properties, the `ErrorCodeExceptionwithErrorCode.IO` has been substituted by a `System.IO.IOException`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.FourHeights.PdfToolbox.LicenseException

| [Class] `PdfTools.FourHeights.PdfToolbox.LicenseException`                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.License`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.FourHeights.PdfToolbox.PasswordException

| [Class] `PdfTools.FourHeights.PdfToolbox.PasswordException`                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception).Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.Password`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.FourHeights.PdfToolbox.Sdk

| [Class] `PdfTools.FourHeights.PdfToolbox.Sdk`                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method `static bool Initialize(string license, string producerSuffix)`Property `static string Version { get ...}``static string ProducerFullName { get...}`.See [The Sdk class](dotnet-interface.mdx#the-sdk-class). |

#### PdfTools.Pdf.StringMap

| [Class] `PdfTools.Pdf.StringMap` → `PdfTools.FourHeights.PdfToolbox.Pdf.StringMap`                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of iDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.FourHeights.PdfToolbox.UnknownFormatException

| [Class] `PdfTools.FourHeights.PdfToolbox.UnknownFormatException`                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception). Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.UnknownFormat`. See [Exceptions](dotnet-interface.mdx#exceptions). |

#### PdfTools.FourHeights.PdfToolbox.UnsupportedFeatureException

| [Class] `PdfTools.FourHeights.PdfToolbox.UnsupportedFeatureException`                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#pdftoolserrorcodeexception). Substitutes the removed property `ErrorCodeException.Code` with value `ErrorCode.UnsupportedFeature`. See [Exceptions](dotnet-interface.mdx#exceptions). |

## Geometry namespace

#### PdfTools.Pdf.Rotation

| [Enum.] `PdfTools.Pdf.Rotation` → `PdfTools.FourHeights.PdfToolbox.Geometry.Rotation` |
| ------------------------------------------------------------------------------------- |
| Renamed enum value `NoRotation`→ `None`.                                              |

#### PdfTools.Pdf.TextAlignment

| [Enum.] `PdfTools.Pdf.TextAlignment`→ `PdfTools.FourHeights.PdfToolbox.Geometry.HorizontalAlignment` |
| ---------------------------------------------------------------------------------------------------- |
|                                                                                                      |

### Pdf.Geometry.Integer namespace

| [Struct] `PdfTools.FourHeights.PdfToolbox.Geometry.Integer.Size`                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fields: `int Width``int Height`Used in [`Image`](#pdftoolspdfimage) and [`ImageMask`](#pdftoolspdfimagemask) to substitute the removed properties `Image.Width`, `Image.Height`, `ImageMask.Width`, and `ImageMask.Height`. See [Image size and image mask size](dotnet-interface.mdx#image-size-and-image-mask-size). |

### Geometry.Real namespace

#### PdfTools.Point

| [Struct] `PdfTools.Point` → `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Point`                                     |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.Rectangle

| [Struct] `PdfTools.Rectangle`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Rectangle`                              |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.Size

| [Struct] `PdfTools.Size`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.Size`                                        |
| --------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.Pdf.Transformation

| [Class → Struct] `PdfTools.Pdf.Transformation`→ `PdfTools.FourHeights.PdfToolbox.Geometry.Real.AffineTransform`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types).Removed copy constructor.Changed behavior of default constructor. Now returns an invalid `AffineTransform` object with all fields default initialized to `0`. Use property `Identity` to obtain a valid object.See [Affine transform objects should be initialized](dotnet-interface.mdx#affine-transform-objects-should-be-initialized).Removed method `Rotate`.Renamed method `RotateAround` → `Rotate`.Changed method `Point TransformPoint(Point)`: Changed both the return type `Point` and the argument `typePoint` from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types).New properties:`double A``double B``double C``double D``double E``double F`New property `static AffineTransform Identity { get... }`. See [Affine transform objects should be initialized](dotnet-interface.mdx#affine-transform-objects-should-be-initialized).  |

## Pdf namespace

#### PdfTools.Pdf.Conformance

| [Enum.] `PdfTools.Pdf.Conformance` → `PdfTools.FourHeights.PdfToolbox.Pdf.Conformance`                     |
| ---------------------------------------------------------------------------------------------------------- |
| Removed enum value `Unknown`. See [Unknown PDF conformance](dotnet-interface.mdx#unknown-pdf-conformance). |

#### PdfTools.Pdf.CopyOption

| [Enum.] `PdfTools.Pdf.CopyOption`                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed. Substituted by [`Pdf.PageCopyOptions`](#pdftoolsfourheightspdftoolboxpdfpagecopyoptions) and [`Pdf.Navigation.OutlineCopyOptions`](#pdftoolsfourheightspdftoolboxpdfnavigationoutlinecopyoptions). See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.CopyStrategy

| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.CopyStrategy`                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`Copy`FlattenRemoveSubstitutes the removed `CopyOption`. See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.Document

| [Class] `PdfTools.Pdf.Document` → `PdfTools.FourHeights.PdfToolbox.Pdf.Document`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed property `OutlineItems` → `Outline`.Changed type of property `OutputIntent` from [`ColorSpace`](#pdftoolspdfcolorspace) to [`Pdf.Content.IccBasedColorSpace`](#pdftoolsfourheightspdftoolboxpdfcontenticcbasedcolorspace). See [Color space classes](dotnet-interface.mdx#color-space-classes).Renamed property `EmbeddedFiles` → `AllEmbeddedFiles`. Changed behavior: Appending is not supported anymore. This is a read-only list of all embedded files and all files in [`FileAttachmentAnnotation`](#pdftoolspdffileattachmentannotation). See [Embedded/Associated/Attached files](dotnet-interface.mdx#embeddedassociatedattached-files).Changed behavior of property `Conformance` for output documents: Always returns the current conformance instead of `removedConformance.Unknown`.Changed signature of method `Document Create(stream streamDesc, Conformance conformance, EncryptionParams encryption)` → `static Pdf.Document Create(Stream streamDesc, Pdf.Conformance? Conformance, Pdf.Encryption Encryption)` Specifically, a `null` value for the second argument is now legal. See [Unknown PDF conformance](dotnet-interface.mdx#unknown-pdf-conformance).Removed and substituted the following methods:`CreateFileReference` → `Pdf.FileReference.Create``CreateMetadata` → `Pdf.Metadata.Create``CreatePage` → `Pdf.Page.Create``CreateCircleAnnotation` → `Pdf.Annotations.EllipseAnnotation.Create``CreateCustomStampAnnotation` → `Pdf.Annotations.CustomStamp.Create``CreateFileAttachmentAnnotation` → `Pdf.Annotations.FileAttachment.Create``CreateFreeDrawingAnnotation` → `Pdf.Annotations.InkAnnotation.Create``CreateFreeTextAnnotation` → `Pdf.Annotations.FreeText.Create``CreateLineAnnotation` → `Pdf.Annotations.LineAnnotation.Create``CreatePolyLineAnnotation` → `Pdf.Annotations.PolyLineAnnotation.Create``CreatePolygonAnnotation` → `Pdf.Annotations.PolygonAnnotation.Create``CreateSquareAnnotation` → `Pdf.Annotations.RectangleAnnotation.Create``CreateStickyNoteAnnotation` → `Pdf.Annotations.StickyNote.Create``CreateTextStampAnnotationRaw` → `Pdf.Annotations.TextStamp.CreateRaw``CreateAlphaPaint,CreateBlendingPaint,CreateSolidPaint` → `Pdf.Content.Paint.Create`. See [Unified paint creation](dotnet-interface.mdx#unified-paint-creation).`CreateDeviceColorSpace` → `Pdf.Content.ColorSpace.CreateProcessColorSpace``CreateFont` → `Pdf.Content.Font.Create``CreateGroup` → `Pdf.Content.Group.Create``CreateICCColorSpace` → `Pdf.Content.IccBasedColorSpace.Create``CreateImageMask` → `Pdf.Content.ImageMask.Create``CreateImage` → `Pdf.Content.Image.Create``CreateSystemFont` → `Pdf.Content.Font.CreateFromSystem``CreateText` → `Pdf.Content.Text.Create``CreateCheckBoxField` → `Pdf.Forms.CheckBoxField.Create``CreateCombTextField` → `Pdf.Forms.CombTextField.Create``CreateComboBoxField` → `Pdf.Forms.ComboBoxField.Create``CreateGeneralTextField` → `Pdf.Forms.GeneralTextField.Create``CreateListBoxField` → `Pdf.Forms.ListBoxField.Create``CreateRadioButtonField` → `Pdf.Forms.RadioButtonField.Create``CreateSubForm` → `Pdf.Forms.SubForm.Create``CreateNamedDestination` → `Pdf.Navigation.NamedDestination.Create``CreateOutlineItem` → `Pdf.Navigation.OutlineItem.Create``CopyFileReference` → `Pdf.FileReference.Copy``CopyMetadata` → `Pdf.Metadata.Copy``CopyPage` → `Pdf.Page.Copy``CopyAnnotation` → `Pdf.Annotations.Annotation.Copy``CopyColorSpace` → `Pdf.Content.ColorSpace.Copy``CopyContentElement` → `Pdf.Content.ContentElement.Copy``CopyGroupElementWithoutContent` → `Pdf.Content.GroupElement.CopyWithoutContent``CopyPageAsGroup` → `Pdf.Content.Group.CopyFromPage``CopyFormFieldNode` → `Pdf.Forms.FormFieldNode.Copy``CopyViewerSettings` → `Pdf.Navigation.ViewerSettings.Copy``CopyOutlineItem` → `Pdf.Navigation.OutlineItem.Copy`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.FileReferenceList PlainEmbeddedFiles {get...}`. This is a list of all embedded files that are neither associated nor contained in a [`FileAttachmentAnnotation`](#pdftoolspdffileattachmentannotation). See [Embedded/Associated/Attached files](./dotnet-interface.mdx#embeddedassociatedattached-files). |

#### PdfTools.Pdf.EncryptionParams

| [Struct → Class] `PdfTools.Pdf.EncryptionParams` → `PdfTools.FourHeights.PdfToolbox.Pdf.Encryption` |
| --------------------------------------------------------------------------------------------------- |
| New constructor `Encryption(string userPassword, string ownerPassword, Permission permissions)`.    |

#### PdfTools.Pdf.FileReference

| [Class] `PdfTools.Pdf.FileReference` → `PdfTools.FourHeights.PdfToolbox.Pdf.FileReference`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). New method `static FileReference Create(Document targetDocument, Stream data, string name, string mediaType, string description, System.DateTimeOffset modificationDate)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New method `static FileReference Copy(Document targetDocument, FileReference fileReference)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). |

#### PdfTools.Pdf.FileReferenceList

| [Class] `PdfTools.Pdf.FileReferenceList` → `PdfTools.FourHeights.PdfToolbox.Pdf.FileReferenceList`                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.Metadata

| [Class] `PdfTools.Pdf.Metadata` → `PdfTools.FourHeights.PdfToolbox.Pdf.Metadata`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Producer`. See [The PDF Producer entry](./dotnet-interface.mdx#the-pdf-producer-entry).Removed property `CreationDate2`.Removed property `ModificationDate2`.Changed type of property `CreationDate` from `System.DateTime?` to `System.DateTimeOffset?`.Changed type of property `ModificationDate` from `System.DateTime?` to `System.DateTimeOffset?`.New method `static Metadata Create(Document targetDocument, Stream xmp)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New method `static Metadata Copy(Document targetDocument, Metadata metadata)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.NameConflictResolution

| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.NameConflictResolution`                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`Merge``Rename`Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.Page

| [Class] `PdfTools.Pdf.Page`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Page`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed the type of properties `BleedBox`, `ArtBox`, and `TrimBox` from reference type `Rectangle` to nullable value type `Rectangle?`. See [Value types](dotnet-interface.mdx#value-types).Changed the type of property `MediaBox` from reference type `Rectangle` to value type `Rectangle`. See [Value types](dotnet-interface.mdx#value-types).Renamed method `Crop` → `UpdateSize`. Changed argument type `Rectangle` from reference type to value type.New property `Pdf.Forms.WidgetList FormFieldWidgets { get...}`. See [Annotations](dotnet-interface.mdx#annotations).New property `Pdf.Navigation.LinkList Links { get...}`. See [Annotations](dotnet-interface.mdx#annotations).New method `static Page Create(Document targetDocument, Geometry.Real.Size size)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New method `static Page Copy(Document targetDocument, Page page, PageCopyOptions options)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.PageCopyOptions

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.PageCopyOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Members: Constructor `PageCopyOptions()`Property `Pdf.CopyStrategy Links { get... set... }` Default: `CopyStrategy.Copy`Property `Pdf.Forms.FormFieldCopyStrategy FormFields { get... set... }` Default: `FormFieldCopyStrategy.Copy`Property `Pdf.CopyStrategy SignedSignatures { get... set... }` Default: `CopyStrategy.Copy`Property `Pdf.CopyStrategy Annotations { get... set... }` Default: `CopyStrategy.Copy`Property `bool CopyOutlineItems { get... set... }` Default: `true`Property `bool CopyAssociatedFiles { get... set... }` Default: `true`Property `bool CopyLogicalStructure { get... set... }` Default: `true`Property `Pdf.NameConflictResolution FormFieldConflictResolution { get... set... }` Default: `NameConflictResolution.Merge`Property `Pdf.Navigation.NamedDestinationCopyStrategy NamedDestinations { get... set... }` Default: `NamedDestinationCopyStrategy.Copy`Property `bool OptimizeResources { get... set... }` Default: `true` Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.PageList

| [Class] `PdfTools.Pdf.PageList` → `PdfTools.FourHeights.PdfToolbox.Pdf.PageList`                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.Permission

| [Enum.] `PdfTools.Pdf.Permission` → `PdfTools.FourHeights.PdfToolbox.Pdf.Permission` |
| ------------------------------------------------------------------------------------ |
|                                                                                      |

| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.RemovalStrategy`                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `Flatten``Remove`Substitutes the removed [`CopyOption`](#pdftoolspdfcopyoption). See [Copy options](dotnet-interface.mdx#copy-options). |

### Pdf.Annotations namespace

#### PdfTools.Pdf.Annotation

| [Class] `PdfTools.Pdf.Annotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Annotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx).Renamed property `Rectangle` → `BoundingBox`. Changed type `Rectangle` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types).Removed property `DoPrint`.New property `NoPrint` with reversed meaning of the removed property `DoPrint`.New method `static Annotation Copy(Pdf.Document targetDocument, Annotation annotation)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [Annotations](dotnet-interface.mdx#annotations). |

#### PdfTools.Pdf.AnnotationLineEnding

| [Enum.] `PdfTools.Pdf.AnnotationLineEnding` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.LineEnding`                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `ReversedOpenArrow` → `OpenArrowTail`.Renamed enum value `ReversedClosedArrow` → `ClosedArrowTail`. |

#### PdfTools.Pdf.AnnotationList

| [Class] `PdfTools.Pdf.AnnotationList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.AnnotationList`                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.AnnotationPopup

| [Class] `PdfTools.Pdf.AnnotationPopup` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Popup`                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed property `Rectangle` → `BoundingBox`. Changed type `Rectangle` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.Pdf.CircleAnnotation

| [Class] `PdfTools.Pdf.CircleAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.EllipseAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](dotnet-interface.mdx#annotations).New method `static EllipseAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.Content.Stroke stroke, Pdf.Content.Paint fill)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.Content.Paint Fill { get... }`. See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |

#### PdfTools.Pdf.CustomStampAnnotation

| [Class] `PdfTools.Pdf.CustomStampAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.CustomStamp` |
| ----------------------------------------------------------------------------------------------------------- |

| New method `static CustomStampAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#pdftoolspdfstampannotation) for inherited changes.

#### PdfTools.Pdf.DrawingAnnotation

| [Class] `PdfTools.Pdf.DrawingAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.DrawingAnnotation` |
| -------------------------------------------------------------------------------------------------------------- |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes.                                  |

#### PdfTools.Pdf.FileAttachmentAnnotation

| [Class] `PdfTools.Pdf.FileAttachmentAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FileAttachment`                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FileAttachmentAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, Pdf.FileReference attachedFile, Pdf.Content.Paint paint)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |

#### PdfTools.Pdf.FileAttachmentIcon

| [Enum.] `PdfTools.Pdf.FileAttachmentIcon` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FileAttachmentIcon` |
| ---------------------------------------------------------------------------------------------------------------- |
|                                                                                                                  |

#### PdfTools.Pdf.FreeDrawingAnnotation

| [Class] `PdfTools.Pdf.FreeDrawingAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.InkAnnotation`                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed base class to class `DrawingAnnotation`. See [Annotations](dotnet-interface.mdx#annotations).New method `static InkAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |

#### PdfTools.Pdf.FreeTextAnnotation

| [Class] `PdfTools.Pdf.FreeTextAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.FreeText`                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New method `static FreeText Create(Pdf.Document targetDocument, Geometry.Real.RectangleboundingBox, stringcontent, Pdf.Content.Paint paint)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |

#### PdfTools.Pdf.HighlightAnnotation

| [Class] `PdfTools.Pdf.HighlightAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Highlight` |
| ------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes.                   |

#### PdfTools.Pdf.LineAnnotation

| [Class] `PdfTools.Pdf.LineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.LineAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type `Point` of property `Startfrom` reference type to value type. See [Value types](dotnet-interface.mdx#value-types).Changed type `Point` of property `Endfrom` reference type to value type. See [Value types](dotnet-interface.mdx#value-types).New method `static LineAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Point start, Geometry.Real.Point end, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |

#### PdfTools.Pdf.MarkupAnnotation

| [Class] `PdfTools.Pdf.MarkupAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupAnnotation` |
| ------------------------------------------------------------------------------------------------------------ |
| See [`Annotation`](#pdftoolspdfannotation) for inherited changes.                                            |

#### PdfTools.Pdf.MarkupInfo

| [Class] `PdfTools.Pdf.MarkupInfo` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupInfo` |
| ------------------------------------------------------------------------------------------------ |
|                                                                                                  |

#### PdfTools.Pdf.MarkupInfoList

| [Class] `PdfTools.Pdf.MarkupInfoList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.MarkupInfoList` |
| -------------------------------------------------------------------------------------------------------- |
|                                                                                                          |

#### PdfTools.Pdf.PolyDrawingAnnotation

| [Class] `PdfTools.Pdf.PolyDrawingAnnotation`                  |
| ------------------------------------------------------------- |
| Removed. See [Annotations](dotnet-interface.mdx#annotations). |

#### PdfTools.Pdf.PolyLineAnnotation

| [Class] `PdfTools.Pdf.PolyLineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.PolyLineAnnotation`                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed base class to class `DrawingAnnotation`. See [Annotations](dotnet-interface.mdx#annotations).New method `static PolyLineAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |

#### PdfTools.Pdf.PolygonAnnotation

| [Class] `PdfTools.Pdf.PolygonAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.PolygonAnnotation`                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](dotnet-interface.mdx#annotations).New method `static PolygonAnnotation Create(Pdf.Document targetDocument, Pdf.Content.Path path, Pdf.Content.Stroke stroke)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-method). See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes.  |

#### PdfTools.Pdf.ShapeDrawingAnnotation

| [Class] `PdfTools.Pdf.ShapeDrawingAnnotation`                 |
| ------------------------------------------------------------- |
| Removed. See [Annotations](dotnet-interface.mdx#annotations). |

#### PdfTools.Pdf.SquareAnnotation

| [Class] `PdfTools.Pdf.SquareAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.RectangleAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#pdftoolspdfdrawingannotation). See [Annotations](dotnet-interface.mdx#annotations).New method `static PolylineAnnotation Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.Content.Stroke stroke, Pdf.Content.Fill fill)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods).New property `Pdf.Content.Fill Fill { get... }`. See [`DrawingAnnotation`](#pdftoolspdfdrawingannotation) for inherited changes. |

#### PdfTools.Pdf.SquigglyAnnotation

| [Class] `PdfTools.Pdf.SquigglyAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Squiggly` |
| ------------------------------------------------------------------------------------------------------ |
| See [`HighlightAnnotation`](#pdftoolspdfhighlightannotation) for inherited changes.                    |

#### PdfTools.Pdf.StampAnnotation

| [Class] `PdfTools.Pdf.StampAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Stamp` |
| ------------------------------------------------------------------------------------------------ |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes.                    |

#### PdfTools.Pdf.StickyNoteAnnotation

| [Class] `PdfTools.Pdf.StickyNoteAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.StickyNote`                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New method `static StickyNote Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, string content, Pdf.Content.Paint paint)`. See [Creation and copying](dotnet-interface.mdx#creation-and-copying) methods. See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes. |

#### PdfTools.Pdf.StrikeThroughAnnotation

| [Class] `PdfTools.Pdf.StrikeThroughAnnotation`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.StrikeThrough` |
| --------------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes.                           |

#### PdfTools.Pdf.TextInsertAnnotation

| [Class] `PdfTools.Pdf.TextInsertAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextInsert` |
| ---------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes.                      |

#### PdfTools.Pdf.TextMarkupAnnotation

| [Class] `PdfTools.Pdf.TextMarkupAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextMarkup` |
| ---------------------------------------------------------------------------------------------------------- |
| See [`MarkupAnnotation`](#pdftoolspdfmarkupannotation) for inherited changes.                              |

#### PdfTools.Pdf.TextStampAnnotation

| [Class] `PdfTools.Pdf.TextStampAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextStamp`                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static TextStamp Create(Pdf.Document targetDocument, Geometry.Real.Point topleft, double?height, TextStampType type, string content)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#pdftoolspdfstampannotation) for inherited changes. |

#### PdfTools.Pdf.TextStampType

| [Enum.] `PdfTools.Pdf.TextStampType` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.TextStampType` |
| ------------------------------------------------------------------------------------------------------ |
|                                                                                                        |

#### PdfTools.Pdf.UnderlineAnnotation

| [Class] `PdfTools.Pdf.UnderlineAnnotation` → `PdfTools.FourHeights.PdfToolbox.Pdf.Annotations.Underline` |
| -------------------------------------------------------------------------------------------------------- |
| See [`TextMarkupAnnotation`](#pdftoolspdftextmarkupannotation) for inherited changes.                    |

### Pdf.Content namespace

#### PdfTools.Pdf.BlendMode

| [Enum.] `PdfTools.Pdf.BlendMode`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.BlendMode` |
| ----------------------------------------------------------------------------------------- |
|                                                                                           |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedGrayColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedGrayColorSpace`                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedRgbColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedRgbColorSpace`                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedCmykColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.CalibratedCmykColorSpace`                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.ColorSpace

| [Class] `PdfTools.Pdf.ColorSpace` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ColorSpace`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Renamed property `Components` → `ComponentCount`.Removed property `Type`.Removed property `Name`.New method `static ColorSpace CreateProcessColorSpace(Pdf.Document targetDocument, Pdf.Content.ProcessColorSpaceType type)`New method `static ColorSpace Copy(Pdf.Document targetDocument, ColorSpace colorSpace)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods). See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.ColorSpaceType

| [Enum.] `PdfTools.Pdf.ColorSpaceType`                                         |
| ----------------------------------------------------------------------------- |
| Removed. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.Content

| [Class] `PdfTools.Pdf.Content`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Content`                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.ContentElement

| [Class] `PdfTools.Pdf.ContentElement`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Rectangle` of property `BoundingBox` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types).Changed type `Transformation` → `Geometry.Real.AffineTransform` of property `Transform` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types).New method `static Content elementCopy(Pdf.Document targetDocument, ContentElement contentElement)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.ContentExtractor

| [Class] `PdfTools.Pdf.ContentExtractor`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentExtractor`                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.ContentGenerator

| [Class] `PdfTools.Pdf.ContentGenerator`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ContentGenerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changed method `void PaintPath(Path path, Paint fill,StrokeParams stroke, bool intersectClipping)`→ `void PaintPath(Path path,Fill fill, Stroke stroke)`. See [Separate inside rule from path](dotnet-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](dotnet-interface.mdx#path-and-text-clipping-operations).Changed behavior of methods `PaintImage` and `PaintImageMask`: Value `null` for second argument of type `Rectangle` is not supported anymore.New method `void ClipWithPath(Pdf.Content.Path path, Pdf.Content.InsideRule InsideRule)`. See [Separate inside rule from path](dotnet-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](dotnet-interface.mdx#path-and-text-clipping-operations).New method `void ClipWithText(Pdf.Content.Text text)`. See [Path and text clipping operations](dotnet-interface.mdx#path-and-text-clipping-operations).  |

#### PdfTools.Pdf.DeviceColorSpaceType

| [Enum.] `PdfTools.Pdf.DeviceColorSpaceType` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ProcessColorSpaceType` |
| ----------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `RGB` → `Rgb`.Renamed enum value `CMYK` → `Cmyk`.                   |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceGrayColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceGrayColorSpace`                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceCmykColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceCmykColorSpace` |
| -------------------------------------------------------------------------- |

| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes).

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceRgbColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.DeviceRgbColorSpace`                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.FillParams

| [Struct → class] `PdfTools.Pdf.FillParams[struct → class]→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Fill`                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed constructor `FillParams(Paint paint, InsideRule fillRule)`.Renamed property `FillRule` → `InsideRule`. See [Separate inside rule from path](dotnet-interface.mdx#separate-inside-rule-from-path).New constructor `Fill(Paint paint)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.Font

| [Class] `PdfTools.Pdf.Font`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Font`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). Renamed method `GetCharWidth→GetCharacterWidth`.New method `static Font Create(Pdf.Document targetDocument, Stream stream, bool embedded)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New method `static Font CreateFromSystem(Pdf.Document targetDocument, string family,string style, bool embedded)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.Group

| [Class] `PdfTools.Pdf.Group`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Group`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Size` of property `Size` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types).New method `static Group Create(Pdf.Document targetDocument, Geometry.Real.Size size)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New method `static Group CreateFromPage(Pdf.Document targetDocument, Pdf.Page page,Pdf.PageCopyOptions copyOptions)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.GroupElement

| [Class] `PdfTools.Pdf.GroupElement`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.GroupElement`                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static GroupElement CopyWithoutContent(Pdf.Document targetDocument, Group Element groupElement)` See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.IccBasedColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.IccBasedColorSpace` |
| ------------------------------------------------------------------------ |

| Extends [Pdf.Content.ColorSpace](#pdftoolspdfcolorspace). 
Method `static Pdf.Content.IccBasedColorSpace Create(Pdf.Document targetDocument, Stream profile)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes).

#### PdfTools.Pdf.Image

| [Class] `PdfTools.Pdf.Image`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Image`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Width`. Replaced by new property `Size`.Removed property `Height`. Replaced by new property `Size`.New method `static ImageCreate(Pdf.Document targetDocument, Stream stream)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New property `Geometry.Integer.SizeSize { get... }`. See [Image size and image mask size](dotnet-interface.mdx#image-size-and-image-mask-size). |

#### PdfTools.Pdf.ImageElement

| [Class] `PdfTools.Pdf.ImageElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageElement` |
| ------------------------------------------------------------------------------------------------ |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes.                          |

#### PdfTools.Pdf.ImageMask

| [Class] `PdfTools.Pdf.ImageMask` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageMask`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Removed property `Width`. Replaced by nsew property `Size`.Removed property `Height`. Replaced by new property `Size`.New method `static ImageMask Create(Pdf.Document targetDocument, Stream stream)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New property `Geometry.Integer.SizeSize { get... }`. See [Image size and image mask size](dotnet-interface.mdx#image-size-and-image-mask-size). |

#### PdfTools.Pdf.ImageMaskElement

| [Class] `PdfTools.Pdf.ImageMaskElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ImageMaskElement` |
| -------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes.                                  |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.IndexedColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.IndexedColorSpace`                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.InsideRule

| [Enum.] `PdfTools.Pdf.InsideRule`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.InsideRule` |
| ------------------------------------------------------------------------------------------- |
|                                                                                             |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.LabColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LabColorSpace`                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.LineCapStyle

| [Enum.] `PdfTools.Pdf.LineCapStyle`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LineCapStyle` |
| ----------------------------------------------------------------------------------------------- |
|                                                                                                 |

#### PdfTools.Pdf.LineJoinStyle

| [Enum.] `PdfTools.Pdf.LineJoinStyle`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.LineJoinStyle` |
| ------------------------------------------------------------------------------------------------- |
|                                                                                                   |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.NChannelColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.NChannelColorSpace`                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.Paint

| [Class] `PdfTools.Pdf.Paint` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Paint`                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static PaintCreate(Pdf.Document targetDocument, Pdf.Content.ColorSpace colorSpace, double[]color, Pdf.Content.Transparency transparency)`. See [Creation and copying methods](dotnet-interface.mdx#creation-and-copying-methods) and [Unified paint creation](dotnet-interface.mdx#unified-paint-creation). |

#### PdfTools.Pdf.Path

| [Class] `PdfTools.Pdf.Path` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Path`                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed constructor `Path(FillRule rule)` → `Path()`. See [Separate inside rule from path](dotnet-interface.mdx#separate-inside-rule-from-path). |

#### PdfTools.Pdf.PathElement

| [Class] `PdfTools.Pdf.PathElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.PathElement`                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type `Rectangle` of property `AlignmentBox` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types). See [ContentElement](#pdftoolspdfcontentelement) for inherited changes. |

#### PdfTools.Pdf.PathGenerator

| [Class] `PdfTools.Pdf.PathGenerator` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.PathGenerator`                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed types `Point` and `Rectangle` (used in all methods) from reference type to value type. See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Content.SeparationColorSpace

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Content.SeparationColorSpace`                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`Pdf.Content.ColorSpace`](#pdftoolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](dotnet-interface.mdx#color-space-classes). |

#### PdfTools.Pdf.ShadingElement

| [Class] `PdfTools.Pdf.ShadingElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.ShadingElement` |
| ---------------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes.                              |

#### PdfTools.Pdf.StrokeParams

| [Struct → class] `PdfTools.Pdf.StrokeParams`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Stroke`                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `StrokeParams(Paint paint, double lineWidth, LineCapStyle lineCapStyle, LineJoinStyle lineJoinStyle, double[] dashArray, double dashPhase, double miterLimit).` New constructor `Stroke(Paint paint, double lineWidth)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.Text

| [Class] `PdfTools.Pdf.Text` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Text`                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static TextCreate(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.TextElement

| [Class] `PdfTools.Pdf.TextElement` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextElement` |
| ---------------------------------------------------------------------------------------------- |
| See [ContentElement](#pdftoolspdfcontentelement) for inherited changes.                        |

#### PdfTools.Pdf.TextFragment

| [Class] `PdfTools.Pdf.TextFragment` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextFragment`                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Renamed property `UnicodeString` → `Text`.Changed type `Rectangle` of property `BoundingBox` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types).  |

#### PdfTools.Pdf.TextGenerator

| [Class] `PdfTools.Pdf.TextGenerator` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.TextGenerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed constructor from `TextGenerator(Text text, Font font, double fontSize, Point location)` → `TextGenerator(Text text, Font font, double fontSize, Geometry.Real.Point?location)` Removed method `SetRendering`. Replaced by properties `Fill` and `Stroke`. See [Text generator](dotnet-interface.mdx#text-generator).Renamed property `CharSpacing` → `CharacterSpacing`. See [Renaming](dotnet-interface.mdx#renaming).New property `PaintFill { get... set... }`.New property `Stroke Stroke { get... set... }`. |

| [Struct → class] `PdfTools.Pdf.TransparencyParams`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Content.Transparency`                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor `TransparencyParams(BlendMode blendMode, double constAlpha)`.Renamed property `ConstAlpha` → `Alpha`.New constructor `Transparency(double alpha)`. |

#### PdfTools.Pdf.UngroupingSet

| [Enum.] `PdfTools.Pdf.UngroupingSet` → `PdfTools.FourHeights.PdfToolbox.Pdf.Content.UngroupingSelection` |
| -------------------------------------------------------------------------------------------------------- |
|                                                                                                          |

### Pdf.Forms namespaces

#### PdfTools.Pdf.CheckBoxField

| [Class] `PdfTools.Pdf.CheckBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.CheckBox`                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CheckBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [FormField](#pdftoolspdfformfield) for inherited changes. |

#### PdfTools.Pdf.ChoiceField

| [Class] `PdfTools.Pdf.ChoiceField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceField` |
| -------------------------------------------------------------------------------------------- |
| See [FormField](#pdftoolspdfformfield) for inherited changes.                                |

#### PdfTools.Pdf.ChoiceItem

| [Class] `PdfTools.Pdf.ChoiceItem` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceItem`                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.ChoiceItemList

| [Class] `PdfTools.Pdf.ChoiceItemList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ChoiceItemList`                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.ComboBoxField

| [Class] `PdfTools.Pdf.ComboBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ComboBox`                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ComboBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)See [ChoiceField](#pdftoolspdfchoicefield) for inherited changes. |

#### PdfTools.Pdf.CombTextField

| [Class] `PdfTools.Pdf.CombTextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.CombTextField`                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CombTextField Create(Pdf.Document targetDocument, int maxLength)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New property `int MaxLength { get... set... }`. See [MaxLength in text fields](dotnet-interface.mdx#maxlength-in-text-fields). See [TextField](#pdftoolspdftextfield) for inherited changes. |

#### PdfTools.Pdf.FormField

| [Class] `PdfTools.Pdf.FormField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.Field` |
| ------------------------------------------------------------------------------------ |

| Changed type `Rectangle` of argument in method `AddNewWidget` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes.

#### PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FormFieldCopyStrategy

| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FormFieldCopyStrategy`                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values: `Copy``Flatten``Remove``CopyAndUpdateWidgets`Substitutes the removed `CopyOption`. See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.FormFieldNode

| [Class] `PdfTools.Pdf.FormFieldNode` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FieldNode`                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static FieldNode Copy(Pdf.Document targetDocument, FieldNode fieldNode)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) |

#### PdfTools.Pdf.FormFieldNodeMap

| [Class] `PdfTools.Pdf.FormFieldNodeMap` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.FieldNodeMap`                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.GeneralTextField

| [Class] `PdfTools.Pdf.GeneralTextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.GeneralTextField` |
| ------------------------------------------------------------------------------------------------------ |

| New method `static GeneralTextField Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)
New property `int? MaxLength { get... set... }`. See [MaxLength in text fields](dotnet-interface.mdx#maxlength-in-text-fields). See [TextField](#pdftoolspdftextfield) for inherited changes. |

#### PdfTools.Pdf.ListBoxField

| [Class] `PdfTools.Pdf.ListBoxField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.ListBox`                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ListBox Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [ChoiceField](#pdftoolspdfchoicefield) for inherited changes. |

#### PdfTools.Pdf.PushButtonField

| [Class] `PdfTools.Pdf.PushButtonField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.PushButton` |
| ----------------------------------------------------------------------------------------------- |
|                                                                                                 |

#### PdfTools.Pdf.RadioButton

| [Class] `PdfTools.Pdf.RadioButton` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButton`                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Changed type `Rectangle` of argument in method `AddNewWidget` from reference type to value type. See [Value types](dotnet-interface.mdx#value-types). |

#### PdfTools.Pdf.RadioButtonField

| [Class] `PdfTools.Pdf.RadioButtonField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButtonGroup`                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed property `CanToggleOff`.New method `static RadioButtonGroup Create(Pdf.Document targetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [FormField](#pdftoolspdfformfield) for inherited changes. |

#### PdfTools.Pdf.RadioButtonList

| [Class] `PdfTools.Pdf.RadioButtonList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.RadioButtonList`                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.SignatureField

| [Class] `PdfTools.Pdf.SignatureField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SignatureField`                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.SignatureFieldList

| [Class] `PdfTools.Pdf.SignatureFieldList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SignatureFieldList`                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.SubForm

| [Class] `PdfTools.Pdf.SubForm` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.SubForm`                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static SubForm Create(Pdf.DocumenttargetDocument)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes. |

#### PdfTools.Pdf.TextField

| [Class] `PdfTools.Pdf.TextField` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.TextField`                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed property `MaxLength`. See [MaxLength in text fields](dotnet-interface.mdx#maxlength-in-text-fields). See [FormFieldNode](#pdftoolspdfformfieldnode) for inherited changes. |

#### PdfTools.Pdf.Widget

| [Class] `PdfTools.Pdf.Widget` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.Widget`                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed inheritance from classAnnotation.SeeAnnotations.Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).Duplicated property `Geometry.Real.Rectangle BoundingBox { get...}` from former `baseclassAnnotation`.Duplicated property `bool Hidden { get... }` from former base `classAnnotation`.Duplicated property `bool NoPrint { get...}` from former base `classAnnotation`. |

#### PdfTools.Pdf.WidgetList

| [Class] `PdfTools.Pdf.WidgetList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Forms.WidgetList`                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

### Pdf.Navigation namespace

#### PdfTools.Pdf.Destination

| [Class] `PdfTools.Pdf.Destination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.Destination`                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.DirectDestination

| [Class] `PdfTools.Pdf.DirectDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.DirectDestination` |
| ------------------------------------------------------------------------------------------------------------- |
| See [Destination](#pdftoolspdfdestination) for inherited changes.                                             |

#### PdfTools.Pdf.EmbeddedPdfLink

| [Class] `PdfTools.Pdf.EmbeddedPdfLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.EmbeddedPdfLink`                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).New method `static EmbeddedPdfLink Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, Pdf.FileReference fileReference)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)See [Link](#pdftoolspdflink) for inherited changes. |

#### PdfTools.Pdf.FitHeightDestination

| [Class] `PdfTools.Pdf.FitHeightDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitHeightDestination`                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).New method `static FitHeightDestination Create(Pdf.Document targetDocument,Pdf.Pagepage, bool fitActualContent)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |

#### PdfTools.Pdf.FitPageDestination

| [Class] `PdfTools.Pdf.FitPageDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitPageDestination`                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).New method `static FitPageDestination Create(Pdf.Document targetDocument, Pdf.Pagepage, bool fitActualContent)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes.  |

#### PdfTools.Pdf.FitRectangleDestination

| [Class] `PdfTools.Pdf.FitRectangleDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitRectangleDestination`                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).New method `static FitRectangleDestination Create(Pdf.Document targetDocument, Pdf.Page page, Geometry.Real.Rectangle rectangle)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods) See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |

#### PdfTools.Pdf.FitWidthDestination

| [Class] `PdfTools.Pdf.FitWidthDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.FitWidthDestination` |
| ----------------------------------------------------------------------------------------------------------------- |

| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).
New method `static FitWidthDestination Create(Pdf.Document targetDocument, Pdf.Page page, bool fitActualContent)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination](#pdftoolspdfdirectdestination) for inherited changes. |

#### PdfTools.Pdf.InternalLink

| [Class] `PdfTools.Pdf.InternalLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.InternalLink` |
| --------------------------------------------------------------------------------------------------- |
| See [Link](#pdftoolspdflink) for inherited changes.                                                 |

#### PdfTools.Pdf.Link

| [Class] `PdfTools.Pdf.Link` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.Link`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed inheritance from class `Annotation`. See [Annotations](dotnet-interface.mdx#annotations).Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static Link Copy(Pdf.Document targetDocument, Link link)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)Duplicated property `Geometry.Real.Rectangle BoundingBox { get... }` from former base class `Annotation`.Duplicated property `bool Hidden { get... }` from former base class `Annotation`.Duplicated property `bool NoPrint { get... }` from former base class `Annotation`. |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LinkList

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LinkList` |
| ----------------------------------------------------------------- |
| A list that contains [Link](#pdftoolspdflink) objects.            |

#### PdfTools.Pdf.LocationZoomDestination

| [Class] `PdfTools.Pdf.LocationZoomDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.LocationZoomDestination`                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).New method `static ZoomDestination Create(Pdf.Document targetDocument, Pdf.Page page, double? left, double? top, double? zoom)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [DirectDestination] for inherited changes. |

#### PdfTools.Pdf.NamedDestination

| [Class] `PdfTools.Pdf.NamedDestination` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestination`                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static NamedDestination Create(Pdf.Document targetDocument, string name, DirectDestination target)` See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)See [Destination](#pdftoolspdfdestination) for inherited changes. |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestinationCopyStrategy

| [Enum.] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.NamedDestinationCopyStrategy`                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------- |
| Values:CopyResolveSubstitutes the removed `CopyOption`. See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineCopyOptions

| [Class] `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineCopyOptions`                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| constructor `OutlineCopyOptions()`Property `Pdf.Navigation.NamedDestinationCopyStrategy NamedDestinations { get... set... }` Default: `NamedDestinationCopyStrategy.Copy`Property `bool CopyLogicalStructure { get... set... }` Default: `true`Substitutes the removed `CopyOption`. See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.OutlineItem

| [Class] `PdfTools.Pdf.OutlineItem` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation).New method `static OutlineItem Create(Pdf.Document targetDocument, string title, Destination Destination)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)New method `static OutlineItem Copy(Pdf.Document targetDocument, OutlineItem outlineItem, OutlineCopyOptions options)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [Copy options](dotnet-interface.mdx#copy-options). |

#### PdfTools.Pdf.OutlineItemList

| [Class] `PdfTools.Pdf.OutlineItemList` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.OutlineItemList`                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `IDisposable` interface. See [Removal of IDisposable implementation](dotnet-interface.mdx#removal-of-idisposable-implementation). |

#### PdfTools.Pdf.PageDisplay

| [Class] `PdfTools.Pdf.PageDisplay[struct]→ `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.PageDisplay`                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed type from reference type (class) to value type (struct). See [Value types](dotnet-interface.mdx#value-types).Changed default value of field `Continuous` from `true` to `false`. |

#### PdfTools.Pdf.PageLayout

| [Enum.] `PdfTools.Pdf.PageLayout`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.PageLayout` |
| ---------------------------------------------------------------------------------------------- |
|                                                                                                |

#### PdfTools.Pdf.ViewerNavigationPane

| [Enum.] `PdfTools.Pdf.ViewerNavigationPane`→ `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.ViewerNavigationPane` |
| ------------------------------------------------------------------------------------------------------------------ |
|                                                                                                                    |

#### PdfTools.Pdf.ViewerSettings

| [Class] `PdfTools.Pdf.ViewerSettings` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.ViewerSettings` |
| ------------------------------------------------------------------------------------------------------- |

| Changed type of property `PageDisplay` from reference type `PageDisplay` to nullable value type `PageDisplay?`.New method `static ViewerSettings Copy(Pdf.Document targetDocument, ViewerSettings viewerSettings)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods)

#### PdfTools.Pdf.WebLink

| [Class] `PdfTools.Pdf.WebLink` → `PdfTools.FourHeights.PdfToolbox.Pdf.Navigation.WebLink` |
| ----------------------------------------------------------------------------------------- |

| Removed constructor. See [Constructors](dotnet-interface.mdx#constructors).
New method `static WebLink Create(Pdf.Document targetDocument, Geometry.Real.Rectangle boundingBox, string uri)`. See [Creation and copying methods.](dotnet-interface.mdx#creation-and-copying-methods). See [Link](#pdftoolspdflink) for inherited changes.|

---

## Java interface changes for PDF Toolbox SDK

There are several changes in naming and behavior in the Java interface to bear in mind when migrating from the the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

## Namespaces

The company namespace of PDF Tools AG is `com.pdf_tools`, both in the 3-Heights® PDF Toolbox API and in the PDF Toolbox SDK.

In the 3-Heights® PDF Toolbox API, most interface elements reside in the namespace `com.pdf_tools.pdf`, except for the following type, which reside directly in `com.pdf_tools`:

- Point
- Rectangle
- Size
- ErrorCode
- ErrorCodeException
- FileStream
- MemoryStream
- Stream

The PDF Toolbox SDK introduces the following new namespaces:

| Namespace                                               | Area of usage               |
| ------------------------------------------------------- | --------------------------- |
| `com.pdf_tools.fourheights.pdftoolbox`                  | Base namespace              |
| `com.pdf_tools.fourheights.pdftoolbox.geometry`         | Geometric related           |
| `com.pdf_tools.fourheights.pdftoolbox.geometry.real`    | For floating point numbers  |
| `com.pdf_tools.fourheights.pdftoolbox.geometry.integer` | For integer numbers         |
| `com.pdf_tools.fourheights.pdftoolbox.pdf`              | General PDF related         |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations`  | Annotation related          |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.content`      | Page content related        |
| `com.pdf_tools.fourheights.pdftoolbox.Pdf.Forms`        | Form field related          |
| `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation`   | Document navigation related |

## The Sdk class

### License keys and product version
In the 3-Heights® PDF Toolbox API, the public methods `setLicenseKey` and `getProductVersion` of the common base class `internal.NativeObject` allows setting a license key and querying the version of the API.

In the PDF Toolbox SDK, this functionality has been moved to the class `Sdk`. Specifically:

- `Sdk.initialize` must be called to set a license key. See also [License keys](./README.mdx#license-keys).
- `Sdk.getVersion` gets the API’s version number as a string.

### The PDF Producer entry
In the 3-Heights® PDF Toolbox API, when creating a PDF, the `Metadata` object sets the PDF’s Producer entry via the method `Metadata.setProducer`.

In the PDF Toolbox SDK, the class `pdf.Metadata` has no method `pdf.Metadata.setProducer`. Instead, the Producer entry for all output PDFs is preconfigured as a string consisting of two parts:

1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a license from Pdftools.
2. The second part (the “suffix” part) is configured when calling `Sdk.initialize` as an argument. It is recommended to use the suffix solely for version information.  
   The assembled Producer entry can be obtained after calling `Sdk.initialize` using the method `Sdk.getProducerFullName`.

## AutoCloseable implementation removed

In the PDF Toolbox SDK, the implementation of the `AutoCloseable` interface has been removed from all but the following classes:

- `Document`
- `ContentGenerator`
- `TextGenerator`
- `Stream`

Native resources are now released automatically when getting or appending a page.

## Structs extend NativeBase

In the 3-Heights® PDF Toolbox API, interface elements documented as struct are independent Java classes.

In the PDF Toolbox SDK, these structs are still Java classes, but they now extend `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. As a consequence, an attempt to load the native library (if not already loaded) is done when constructing a struct. This is due to the static constructor in this base class.

## Exceptions

In the PDF Toolbox SDK, the `ErrorCodeException` has been renamed to `PdfToolboxException`. The method `ErrorCodeException.getCode` has been removed and substituted by the following new classes, each extending `PdfToolboxException`:

- `ConformanceException`
- `CorruptException`
- `LicenseException`
- `PasswordException`
- `UnknownFormatException`
- `UnsupportedFeatureException`
  Instead of an `ErrorCodeException` with method `ErrorCodeException.getErrorCodeErrorCode.IO`, a `java.io.IOException` is generated.

## OffsetDateTime

In the 3-Heights® PDF Toolbox API, class members that represent date and time have a type `java.util.Calendar`.

In the PDF Toolbox SDK, dates and times are represented by the type `java.time.OffsetDateTime`.
This affects the following members:

- `Methodpdf.FileReference.getModificationDate`
- `Methodspdf.Metadata.‹get|set›CreationDate`
- `Methodpdf.Metadata.‹get|set›ModificationDate`
- `Methodpdf.forms.SignatureField.getDate`

## Renaming

Some interface elements have been renamed. The following principles apply:

- Interface elements that include abbreviations are now written consistently in Pascal case. For example `RGB` → is now `Rgb`, except for two-letter abbreviations, which are written as two capital letters, such as`IO`.
- Some abbreviations have been changed to full words, for example `Char` → `Character`.
- Some words that are repeated in the introduced namespace have been dropped. For example, `AnnotationPopup` → is now `pdf.annotations.Popup`.
- Improved clarity, brevity, jargon, and technical correctness.

## Affine transform objects should be initialized

In the 3-Heights® PDF Toolbox API, `Transformation` is a class.

In the PDF Toolbox SDK, this element has been renamed to `geometry.real.AffineTransformation`, and its type has changed to struct. Interface elements documented asstruct are still classes in Java, but they behave a little differently.

Specifically, default constructed `geometry.real.AffineTransform` objects are not valid. (A matrix with all values 0 is singular.) Default constructed `geometry.real.AffineTransform` objects should always be initialized with `geometry.real.AffineTransform.getIdentity`.

For example:

```
AffineTransform transform = AffineTransform.getIdentity();
```

## Creation and copying methods

In the 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by static methods `Document.create...` and copied from an input document to an output document by static methods `Document.copy...`. For example, `Document.createPage`, `Document.copyPage`.

In the PDF Toolbox SDK, all these methods have been moved from the `Document` class to the class that is created or copied. For example, method `Document.createPage` → `pdf.Page.create`.

This affects the following classes:

- `Page`
- `Image`
- `ImageMask`
- `Font`
- `Group`
- `ColorSpace`
- `Paint`
- `Text`
- `Metadata`
- `FileReference`
- `SubForm`
- `GeneralTextField`
- `CombTextField`
- `CheckBoxField`
- `RadioButtonField`
- `ListBoxField`
- `ComboBoxField`
- `NamedDestination`
- `OutlineItem`
- `Annotation`
- `Link`
- `FileAttachmentAnnotation`
- `FreeTextAnnotation`
- `StickyNoteAnnotation`
- `TextStampAnnotation`
- `CustomStampAnnotation`
- `CircleAnnotation`
- `SquareAnnotation`
- `LineAnnotation`
- `PolyLineAnnotation`
- `PolygonAnnotation`
- `FreeDrawingAnnotation`
- `ContentElement`
- `FormFieldNode`

## Constructors

In the 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example, `FitPageDestination.FitPageDestination`.

In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with static methods `create` and `copy`.

This affects the following classes:

- `EmbeddedPdfLink`
- `FitHeightDestination`
- `FitPageDestination`
- `FitRectangleDestination`
- `FitWidthDestination`
- `LocationZoomDestination`
- `WebLink`

In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:

- `pdf.Encryption`
- `pdf.content.ContentExtractor`
- `pdf.content.ContentGenerator`
- `pdf.content.Fill`
- `pdf.content.PageCopyOptions`
- `pdf.content.PathGenerator`
- `pdf.content.Path`
- `pdf.content.Stroke`
- `pdf.content.TextGenerator`
- `pdf.content.Transparency`
- `pdf.navigation.OutlineCopyOptions`

## Unknown PDF conformance

In the 3-Heights® PDF Toolbox API, the `Conformance` enumeration has a value `Conformance.UNKNOWN`.
The PDF Toolbox SDK enum `pdf.Conformance` has no such value. The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:

- In the method `pdf.Document.create`, the second argument `pdf.Conformance` is allowed to be `null`, where a `null` value has the same meaning as the removed value `Conformance.UNKNOWN`.
- The method `pdf.Document.getConformance` always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with `null`) the conformance the output PDF would have if closed now.

## Copy options

In the 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the `CopyOption`enum.

In the PDF Toolbox SDK, this enum has been substituted by new classes:

- `pdf.PageCopyOptionsUsed` in methods `pdf.Page.copy` and `pdf.Group.createFromPage`.
- `pdf.navigation.OutlineCopyOptionsUsed` in method `pdf.navigation.OutlineItem.copy`.

Each copying configuration decision is reflected in a class member. Apart from boolean for on-off decisions, the following enumerations model possible choices:

- `pdf.CopyStrategy`
- `pdf.RemovalStrategy`
- `pdf.NameConflictResolution`
- `pdf.forms.FormFieldCopyStrategy`
- `pdf.navigation.NamedDestinationCopyStrategy`

This clarifies the copying behavior and allows sensible default values.

## Color space classes

**Class hierarchy**  
In the 3-Heights® PDF Toolbox API, there is a single class `ColorSpace`, which covers all types of color spaces.

In the PDF Toolbox SDK, the `ColorSpaceType` enumeration and the method `ColorSpace.getType` have been removed. Instead, there are the following new classes, all extending `pdf.content.ColorSpace`:

- `pdf.content.CalibratedGrayColorSpace`
- `pdf.content.CalibratedRgbColorSpace`
- `pdf.content.DeviceCmykColorSpace`
- `pdf.content.DeviceGrayColorSpace`
- `pdf.content.DeviceRgbColorSpace`
- `pdf.content.IccBasedColorSpace`
- `pdf.content.IndexedColorSpace`
- `pdf.content.LabColorSpace`
- `pdf.content.NChannelColorSpace`
- `pdf.content.SeparationColorSpace`

The 3-Heights® PDF Toolbox API color space type `DeviceN` now is subsumed by the more general `pdf.content.NChannelColorSpace`.

**Device color spaces versus process color spaces**  
In the 3-Heights® PDF Toolbox API, the method `Document.createDeviceColorSpace` does not necessarily create a device color space, e.g., in case of PDF/A.

In the PDF Toolbox SDK, the enumeration `DeviceColorSpaceType` has been renamed to `pdf.content.ProcessColorSpaceType`. The class `pdf.content.ColorSpace` now has the following static method:

```
pdf.content.ColorSpaceCreateProcessColorSpace(pdf.DocumenttargetDocument, pdf.content.DeviceColorSpaceType type)
```

This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.

## Embedded/Associated/Attached files

In the 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a `FileAttachmentAnnotation` are jointly listed in the method `Document.getEmbeddedFiles`.

In the PDF Toolbox SDK, embedded files, associated files, and files contained in file attachment annotations are treated separately. A `pdf.Document` now has two lists for appending:

- `pdf.Document.getAssociatedFiles`
- `pdf.Document.getPlainEmbeddedFiles`

The former method `Document.getEmbeddedFiles` has been renamed to `pdf.Document.getAllEmbeddedFiles`, a read-only list that contains embedded files and files contained in `pdf.annotations.FileAttachment` annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the Attachments pane in the Adobe PDF viewer.

## Annotations

In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:

- `FreeDrawingAnnotation` → `pdf.annotations.InkAnnotation`
- `CircleAnnotation` → `pdf.annotations.EllipseAnnotation`
- `SquareAnnotation` → `pdf.annotations.RectangleAnnotation`

The methods `RadioButtenField.getCanToggleOff` and `RadioButtenField.setCanToggleOff` have been removed. In most PDF viewers, there is no support for this feature.

**Class hierarchy**  
In the 3-Heights® PDF Toolbox API, `Widget` and `Link` extend the base class `Annotation`.

In the PDF Toolbox SDK, the classes `pdf.forms.Widget` and `pdf.navigation.Link` have been separated from their former base class. Due to this separation:

- A `pdf.Page` now has the following lists:

  - `pdf.Page.getAnnotations`
  - `pdf.Page.getLinks`
  - `pdf.Page.getFormFieldWidgets`

- The following methods of `pdf.annotations.Annotation` have been replicated in `pdf.forms.Widget` and `pdf.navigation.Link`:

  - `getBoundingBox`
  - `getHidden`
  - `getNoPrint`

The intermediate base classes `PolyDrawingAnnotation` and `ShapeDrawingAnnotation` have been removed. All drawing annotations now directly extend the class `pdf.annotations.DrawingAnnotation`. Those drawing annotations that have a closed path (`pdf.annotations.PolygonAnnotation`, `pdf.annotations.EllipseAnnotation`, `pdf.annotations.RectangleAnnotation`) have methods `getFill` and `setFill`.

**Class hierarchy comparison**

| 3-Heights® PDF Toolbox (left) | PDF Toolbox SDK (right) |
| ----------------------------- | ----------------------- |

![Java class hierarchy comparison diagram](/img/Toolbox_Java-class-comparison.png)

## MaxLength in text fields

In the 3-Heights® PDF Toolbox API, the error behavior of the method `TextField.setMaxLength` depends on the actual underlying class: `GeneralTextField` allows `null` values, while `CombTextField` does not.

In the PDF Toolbox SDK, the methods `TextField.getMaxLength` and `TextField.setMaxLength` have been removedand replicated in the derived classes `pdf.forms.CombTextField` and `pdf.forms.GeneralTextField`, in the latter as a nullable `Integer`.

## Unified paint creation

In the 3-Heights® PDF Toolbox API, there exist three methods for creating a `Paint` object:

- `Document.createSolidPaint`
- `Document.createAlphaPaint`
- `Document.createBlendingPaint`

In the PDF Toolbox SDK, these methods have been replaced by a single static method `pdf.content.Paint.create`. See also [Creation and copying methods](#creation-and-copying-methods).

## Separate inside rule from path

In the 3-Heights® PDF Toolbox API, the constructor `Path.Path` has an argument `InsideRule rule`.

In the PDF Toolbox SDK, this argument is dropped. Instead, the `InsideRule` now is specified in a new member of `pdf.content.Fill` when painting the path with `pdf.content.ContentGenerator.paintPath`, or it is specified ina method argument when clipping with `pdf.content.ContentGenerator.clipWithPath`. This removes ambiguity and allows a separated treatment of the inside rule for path filling and path clipping.

## Path and text clipping operations

In the 3-Heights® PDF Toolbox API, the `ContentGenerator` supports simultaneous clipping and painting operations.

In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:

- The argument `boolean intersectClipPath` has been removed from the method `ContentGenerator.paintPath`.
- The method `TextGenerator.setRendering` has been removed (see also [Text generator](#text-generator)), and its argument `boolean intersectClipping` has been dropped without a replacement.
- The new class `pdf.content.ContentGenerator` has two new methods for path and text clipping operations:

  - `pdf.content.ContentGenerator.clipWithPath`
  - `pdf.content.ContentGenerator.clipWithText`

To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.

## Text generator

In the PDF Toolbox SDK, the method `TextGenerator.setRendering` has been substituted by two separate methods:

- `pdf.content.TextGenerator.setFill`
- `pdf.content.TextGenerator.setStroke`

## Image size and image mask size

In the 3-Heights® PDF Toolbox API, `Image` and `ImageMask` have methods `getWidth` and `getHeight`.

In the PDF Toolbox SDK, these are substituted by methods `pdf.content.Image.getSize` and `pdf.content.ImageMask.getSize`, both of which have the new type `geometry.integer.Size`.

---

## Reference

For all changes in the Java interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see [Java Reference](java-reference.mdx).

---

## Reference for changes in Java interface

This section lists all changes in the Java interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK. Interface elements are ordered alphabetically by PDF Toolbox SDK namespace.

:::info
For the full API reference for the PDF Toolbox SDK, see [Java API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/javadoc/index.html?overview-summary.html).

:::

#### com.pdf_tools.internal.NativeObject

| [Class] `com.pdf_tools.internal.NativeObject` → `com.pdf_tools.fourheights.pdftoolbox.internal.NativeObject`                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed static method `setLicenseKey`.Removed static method `checkLicense`.Removed static method `getProductVersion`. The above have been substituted by new static members in [Sdk](#compdf_toolsfourheightspdftoolboxsdk). |

## Base namespace

#### com.pdf_tools.fourheights.pdftoolbox.ConformanceException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.ConformanceException`                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`PdfToolboxException`](#compdf_toolserrorcodeexception).Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.CONFORMANCE`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.fourheights.pdftoolbox.CorruptException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.CorruptException`                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.CORRUPT`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.ErrorCode

| [Enum.] `com.pdf_tools.ErrorCode` → `com.pdf_tools.fourheights.pdftoolbox.ErrorCode` |
| ------------------------------------------------------------------------------------ |
| Removed. See [Exceptions](./java-interface.mdx#exceptions).                            |

#### com.pdf_tools.ErrorCodeException

| [Class] `com.pdf_tools.ErrorCodeException`→ `com.pdf_tools.fourheights.pdftoolbox.PdfToolboxException`                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed method `getCode`. In all affected methods, the `ErrorCodeExceptionwithErrorCode.IO` has been substituted by a `java.io.IOException`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.fourheights.pdftoolbox.LicenseException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.LicenseException`                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.LICENSE`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.fourheights.pdftoolbox.PasswordException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.PasswordException`                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.PASSWORD`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.fourheights.pdftoolbox.Sdk

| [Class] `com.pdf_tools.fourheights.pdftoolbox.Sdk`                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method `static boolean initialize(String license, String producerSuffix)`Method `static String getVersion()``static String getProducerFullName()`See [The Sdk class](./java-interface.mdx#the-sdk-class). |

#### com.pdf_tools.pdf.StringMap

| [Class] `com.pdf_tools.pdf.StringMap`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.StringMap`                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.fourheights.pdftoolbox.UnknownFormatException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.UnknownFormatException`                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.UNKNOWN_FORMAT`. See [Exceptions](./java-interface.mdx#exceptions). |

#### com.pdf_tools.fourheights.pdftoolbox.UnsupportedFeatureException

| [Class] `com.pdf_tools.fourheights.pdftoolbox.UnsupportedFeatureException`                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Extends [PdfToolboxException](#compdf_toolserrorcodeexception). Substitutes the removed method `ErrorCodeException.getCode` with value `ErrorCode.UNSUPPORTED_FEATURE`. See [Exceptions](./java-interface.mdx#exceptions). |

## geometry namespace

#### com.pdf_tools.pdf.Rotation

| [Enum.] `com.pdf_tools.pdf.Rotation` → `com.pdf_tools.fourheights.pdftoolbox.geometry.Rotation` |
| ----------------------------------------------------------------------------------------------- |
| Renamed enum value `NO_ROTATION` → `NONE`.                                                      |

#### com.pdf_tools.pdf.TextAlignment

| [Enum.] `com.pdf_tools.pdf.TextAlignment` → `com.pdf_tools.fourheights.pdftoolbox.geometry.HorizontalAlignment` |
| --------------------------------------------------------------------------------------------------------------- |
|                                                                                                                 |

### pdf.geometry.integer namespace

#### com.pdf_tools.fourheights.pdftoolbox.geometry.integer.Size

| [Struct] `com.pdf_tools.fourheights.pdftoolbox.geometry.integer.Size`                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `intWidth``intHeight` Used in [`Image`](#compdf_toolspdfimage) and [`ImageMask`](#compdf_toolspdfimagemask) to substitute the removed methods `Image.getWidth`, `Image.getHeight`, `ImageMask.getWidth`, and `ImageMask.getHeight`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |

### geometry.real namespace

#### com.pdf_tools.Point

| [Struct] `com.pdf_tools.Point`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Point`                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base class `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase). |

#### com.pdf_tools.Rectangle

| [Struct] `com.pdf_tools.Rectangle`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Rectangle`                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base classcom.pdf_tools.fourheights.pdftoolbox.internal.NativeBase. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase).Removed method `getWidth`.Removed method `getHeight`.Removed method `getSize`.Removed method `getLeftBottom`.Removed method `getLeftTop`.Removed method `getRightBottom`.Removed method `getRightTop`.Removed method `getCenter`. |

#### com.pdf_tools.Size

| [Struct] `com.pdf_tools.Size`→ `com.pdf_tools.fourheights.pdftoolbox.geometry.real.Size`                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New base `classcom.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase). |

#### com.pdf_tools.pdf.Transformation

| [Class → Struct] `com.pdf_tools.pdf.Transformation` → `com.pdf_tools.fourheights.pdftoolbox.geometry.real.AffineTransform`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed). Removed `copy` constructor.Changed behavior of default constructor. Now returns an `invalidAffineTransform` object with all fieldsdefault initialized to `0`. Use method `getIdentity` to obtain a valid object. See [Affine transform objects should be initialized](./java-interface.mdx#affine-transform-objects-should-be-initialized).Removed method `rotate`.Renamed method `rotateAround` → `rotate`.New fields:`double a``double b``double c``double d``double e``double f`New method `static AffineTransform getIdentity()`. See [Affine transform objects should be initialized](./java-interface.mdx#affine-transform-objects-should-be-initialized). |

## pdf namespace

#### com.pdf_tools.pdf.Conformance

| [Enum.] `com.pdf_tools.pdf.Conformance` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Conformance`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed enum value `UNKNOWN`. See [Unknown PDF conformance.](./java-interface.mdx#unknown-pdf-conformance).Renamed remaining enum values:  `PDF_1_0` → `PDF10``PDF_1_1` → `PDF11``PDF_1_2` → `PDF12``PDF_1_3` → `PDF13``PDF_1_4` → `PDF14``PDF_1_5` → `PDF15``PDF_1_6` → `PDF16``PDF_1_7` → `PDF17``PDF_2_0` → `PDF20``PDFA_1B` → `PDF_A1_B``PDFA_1A` → `PDF_A1_A``PDFA_2B` → `PDF_A2_B``PDFA_2U` → `PDF_A2_U``PDFA_2A` → `PDF_A2_A``PDFA_3B` → `PDF_A3_B``PDFA_3U` → `PDF_A3_U``PDFA_3A` → `PDF_A3_A` |

#### com.pdf_tools.pdf.CopyOption

| [Enum.] `com.pdf_tools.pdf.CopyOption`                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed. Substituted by [`pdf.PageCopyOptions`] and `pdf.navigation.OutlineCopyOptions`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.CopyStrategy

| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.CopyStrategy`                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Values:`COPY``FLATTEN``REMOVE`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.Document

| [Class] `com.pdf_tools.pdf.Document`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Document`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed method `getOutlineItems` → `getOutline`.Changed return and argument type of methods `getOutputIntent` and `setOutputIntent` from `ColorSpace` to `pdf.content.IccBasedColorSpace`. See [Color space classes](./java-interface.mdx#color-space-classes).Renamed method `getEmbeddedFiles` → `getAllEmbeddedFiles`.Appending is not supported anymore. This is a read-only list of all embedded files and all files in `FileAttachmentAnnotation`. See [Embedded/Associated/Attached files.](./java-interface.mdx#embeddedassociatedattached-files).Changed behavior of method `getConformance` for output documents: Always returns the current conformance instead of `removedConformance.UNKNOWN`.Changed behavior of method `create`: For the second argument of type `Conformance`, `null` is now legal. See [Unknown PDF conformance.](./java-interface.mdx#unknown-pdf-conformance).Removed and substituted the following methods: `createFileReference` → `pdf.FileReference.create``createMetadata` → `pdf.Metadata.create``createPage` → `pdf.Page.create``createCircleAnnotation` → `pdf.annotations.EllipseAnnotation.create``createCustomStampAnnotation` → `pdf.annotations.CustomStamp.create``createFileAttachmentAnnotation` → `pdf.annotations.FileAttachment.create``createFreeDrawingAnnotation` → `pdf.annotations.InkAnnotation.create``createFreeTextAnnotation` → `pdf.annotations.FreeText.create``createLineAnnotation` → `pdf.annotations.LineAnnotation.create``createPolyLineAnnotation` → `pdf.annotations.PolyLineAnnotation.create``createPolygonAnnotation` → `pdf.annotations.PolygonAnnotation.create``createSquareAnnotation` → `pdf.annotations.RectangleAnnotation.create``createStickyNoteAnnotation` → `pdf.annotations.StickyNote.create``createTextStampAnnotationRaw` → `pdf.annotations.TextStamp.createRaw``createAlphaPaint, createBlendingPaint, createSolidPaint` → `pdf.content.Paint.create`. See [Unified paint creation](./java-interface.mdx#unified-paint-creation).`createDeviceColorSpace` → `pdf.content.ColorSpace.createProcessColorSpace``createFont` → `pdf.content.Font.create``createGroup` → `pdf.content.Group.create``createICCColorSpace` → `pdf.content.IccBasedColorSpace.create``createImageMask` → `pdf.content.ImageMask.create``createImage` → `pdf.content.Image.create``createSystemFont` → `pdf.content.Font.createFromSystem``createText` → `pdf.content.Text.create``createCheckBoxField` → `pdf.forms.CheckBoxField.create``createCombTextField` → `pdf.forms.CombTextField.create``createComboBoxField` → `pdf.forms.ComboBoxField.create``createGeneralTextField` → `pdf.forms.GeneralTextField.create``createListBoxField` → `pdf.forms.ListBoxField.create``createRadioButtonField` → `pdf.forms.RadioButtonField.create``createSubForm` → `pdf.forms.SubForm.create``createNamedDestination` → `pdf.navigation.NamedDestination.create``createOutlineItem` → `pdf.navigation.OutlineItem.create``copyFileReference` → `pdf.FileReference.copy``copyMetadata` → `pdf.Metadata.copy``copyPage` → `pdf.Page.copy``copyAnnotation` → `pdf.annotations.Annotation.copy``copyColorSpace` → `pdf.content.ColorSpace.copy``copyContentElement` → `pdf.content.ContentElement.copy``copyGroupElementWithoutContent` → `pdf.content.GroupElement.copyWithoutContent``copyPageAsGroup` → `pdf.content.Group.copyFromPage``copyFormFieldNode` → `pdf.forms.FormFieldNode.copy``copyViewerSettings` → `pdf.navigation.ViewerSettings.copy``copyOutlineItem` → `pdf.navigation.OutlineItem.copy` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.FileReferenceList getPlainEmbeddedFiles()`. This is a list of all embedded files that are neither associated nor contained in a `FileAttachmentAnnotation`. See [Embedded/Associated/Attached files](./java-interface.mdx#embeddedassociatedattached-files).  |

#### com.pdf_tools.pdf.EncryptionParams

| [Struct → Class] `com.pdf_tools.pdf.EncryptionParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Encryption` |
| ------------------------------------------------------------------------------------------------------------- |
| New constructor `Encryption(String userPassword, String ownerPassword, Permission permissions)`.              |

#### com.pdf_tools.pdf.FileReference

| [Class] `com.pdf_tools.pdf.FileReference`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.FileReference`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Changed type of method `get ModificationDate` from `java.util.Calendar` to `java.time.OffsetDateTime.SeeOffsetDateTime`.New method `static FileReference create(Document targetDocument, sys.Streamdata, String name, String mediaType, String description, java.time.OffsetDateTime modificationDate)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static FileReference copy(Document targetDocument, FileReference fileReference)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.FileReferenceList

| [Class] `com.pdf_tools.pdf.FileReferenceList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.FileReferenceList`                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |

#### com.pdf_tools.pdf.Metadata

| [Class] `com.pdf_tools.pdf.Metadata`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Metadata`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Removed method `setProducer`. See [The PDF Producer entry](./java-interface.mdx#the-pdf-producer-entry).Changed type of methods `getCreationDate` and `setCreationDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime).Changed type of method `getModificationDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime).New method `static Metadata create(Document targetDocument, sys.Stream xmp)` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Metadata copy(Document targetDocument, Metadata metadata)` See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.NameConflictResolution

| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.NameConflictResolution`                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`MERGE``RENAME`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.Page

| [Class] `com.pdf_tools.pdf.Page`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.Page`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) Renamed method `crop` → `updateSize`.New method `pdf.forms.WidgetList getFormFieldWidgets()`. See [Annotations](./java-interface.mdx#annotations).New method `pdf.navigation.LinkList getLinks()`. See [Annotations](./java-interface.mdx#annotations).New method `static Page create(Document targetDocument, geometry.real.Size size)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Page copy(Document targetDocument, Page page, PageCopyOptions options)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.PageCopyOptions

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.PageCopyOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Members: Constructor `PageCopyOptions()`Methods `pdf.CopyStrategy getLinks()` and `void setLinks(pdf.CopyStrategy Links)` Default: `CopyStrategy.COPY`Methods `pdf.forms.FormFieldCopyStrategy getFormFields()` and `void setFormFields(pdf.forms.FormFieldCopyStrategy FormFields)` Default: `FormFieldCopyStrategy.COPY`Methods `pdf.CopyStrategy getSignedSignatures()` and `void setSignedSignatures(pdf.CopyStrategy SignedSignatures)` Default: `CopyStrategy.COPY`Methods `pdf.CopyStrategy getAnnotations()` and `void setAnnotations(pdf.CopyStrategy Annotations)` Default: `CopyStrategy.COPY`Methods `boolean getCopyOutlineItems()` and `void setCopyOutlineItems(boolean CopyOutlineItems)`Default: `true`Methods `boolean getCopyAssociatedFiles()` and `void setCopyAssociatedFiles(boolean CopyAssociatedFiles)`Default: `true`Methods `boolean getCopyLogicalStructure()` and `void setCopyLogicalStructure(boolean CopyLogicalStructure)`Default: `true`Methods `pdf.NameConflictResolution getFormField ConflictResolution()` and `void setFormFieldConflictResolution(pdf.NameConflictResolution FormFieldConflictResolution)`Default: `NameConflictResolution.MERGE`Methods `pdf.navigation.NamedDestinationCopyStrategy getNamedDestinations()` and `void setNamedDestinations(pdf.navigation.NamedDestinationCopyStrategy NamedDestinations)`Default: `NamedDestinationCopyStrategy.COPY`Methods `boolean getOptimizeResources()` and `void setOptimizeResources(boolean OptimizeResources)`Default: `true` Substitutes the `removedCopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.PageList

| [Class] `com.pdf_tools.pdf.PageList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.PageList`                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |

#### com.pdf_tools.pdf.Permission

| [Enum.] `com.pdf_tools.pdf.Permission` → `com.pdf_tools.fourheights.pdftoolbox.pdf.Permission` |
| ---------------------------------------------------------------------------------------------- |
|                                                                                                |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.RemovalStrategy

| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.RemovalStrategy`                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`FLATTEN` `REMOVE`Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

### pdf.annotations namespace

#### com.pdf_tools.pdf.Annotation

| [Class] `com.pdf_tools.pdf.Annotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Annotation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed)Renamed method `getRectangle` → `getBoundingBox`.Removed method `getDoPrint`.New method `getNoPrint` with reversed meaning of the removed method `getDoPrint`.New method `static Annotationcopy(pdf.Document targetDocument, Annotation annotation)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Annotations](./java-interface.mdx#annotations). |

#### com.pdf_tools.pdf.AnnotationLineEnding

| [Enum.] `com.pdf_tools.pdf.AnnotationLineEnding` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.LineEnding`                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `REVERSED_OPEN_ARROW` → `OPEN_ARROW_TAIL`.Renamed enum value `REVERSED_CLOSED_ARROW` → `CLOSED_ARROW_TAIL`. |

#### com.pdf_tools.pdf.AnnotationList

| [Class] `com.pdf_tools.pdf.AnnotationList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.AnnotationList`                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed implementation of the `AutoCloseable` interface. See [AutoCloseable implementation removed](./java-interface.mdx#autocloseable-implementation-removed) |

#### com.pdf_tools.pdf.AnnotationPopup

| [Class] `com.pdf_tools.pdf.AnnotationPopup`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Popup` |
| --------------------------------------------------------------------------------------------------------- |
| Renamed method `getRectangle` → `getBoundingBox`.                                                         |

#### com.pdf_tools.pdf.CircleAnnotation

| [Class] `com.pdf_tools.pdf.CircleAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.EllipseAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Changed base class to class `DrawingAnnotation`. See [Annotations](./java-interface.mdx#annotations). New method `static EllipseAnnotation create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, pdf.content.Stroke stroke, pdf.content.Paint fill)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.content.Paint getFill()`. See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

#### com.pdf_tools.pdf.CustomStampAnnotation

| [Class] `com.pdf_tools.pdf.CustomStampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.CustomStamp`                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CustomStampAnnotation create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [StampAnnotation](#compdf_toolspdfstampannotation) for inherited changes. |

#### com.pdf_tools.pdf.DrawingAnnotation

| [Class] `com.pdf_tools.pdf.DrawingAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.DrawingAnnotation` |
| ----------------------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes.                                         |

#### com.pdf_tools.pdf.FileAttachmentAnnotation

| [Class] `com.pdf_tools.pdf.FileAttachmentAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FileAttachment`                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FileAttachmentAnnotation create(pdf.Document targetDocument, geometry.real.Point topleft, pdf.FileReference attachedFile, pdf.content.Pain tpaint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |

#### com.pdf_tools.pdf.FileAttachmentIcon

| [Enum.] `com.pdf_tools.pdf.FileAttachmentIcon` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FileAttachmentIcon` |
| -------------------------------------------------------------------------------------------------------------------------- |
|                                                                                                                            |

#### com.pdf_tools.pdf.FreeDrawingAnnotation

| [Class] `com.pdf_tools.pdf.FreeDrawingAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.InkAnnotation`                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class `DrawingAnnotation`. See [Annotations](./java-interface.mdx#annotations).New method `static InkAnnotation create(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

#### com.pdf_tools.pdf.FreeTextAnnotation

| [Class] `com.pdf_tools.pdf.FreeTextAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.FreeText`                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static FreeText create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, String content, pdf.content.Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |

#### com.pdf_tools.pdf.HighlightAnnotation

| [Class] `com.pdf_tools.pdf.HighlightAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Highlight` |
| ----------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes.                           |

#### com.pdf_tools.pdf.LineAnnotation

| [Class] `com.pdf_tools.pdf.LineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.LineAnnotation`                                                                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static LineAnnotation create(pdf.Document targetDocument, geometry.real.Point start, geometry.real.Point end, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

##### com.pdf_tools.pdf.MarkupAnnotation

| [Class] `com.pdf_tools.pdf.MarkupAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupAnnotation` |
| --------------------------------------------------------------------------------------------------------------------- |
| See [Annotation](#compdf_toolspdfannotation) for inherited changes.                                                   |

#### com.pdf_tools.pdf.MarkupInfo

| [Class] `com.pdf_tools.pdf.MarkupInfo`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupInfo` |
| --------------------------------------------------------------------------------------------------------- |
|                                                                                                           |

#### com.pdf_tools.pdf.MarkupInfoList

| [Class] `com.pdf_tools.pdf.MarkupInfoList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.MarkupInfoList` |
| ----------------------------------------------------------------------------------------------------------------- |
|                                                                                                                   |

#### com.pdf_tools.pdf.PolyDrawingAnnotation

| [Class] `com.pdf_tools.pdf.PolyDrawingAnnotation`          |
| ---------------------------------------------------------- |
| Removed. See[Annotations](./java-interface.mdx#annotations). |

#### com.pdf_tools.pdf.PolyLineAnnotation

| [Class] `com.pdf_tools.pdf.PolyLineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.PolyLineAnnotation`                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolyLineAnnotation create(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

#### com.pdf_tools.pdf.PolygonAnnotation

| [Class] `com.pdf_tools.pdf.PolygonAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.PolygonAnnotation`                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolygonAnnotationcreate(pdf.Document targetDocument, pdf.content.Path path, pdf.content.Stroke stroke)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

#### com.pdf_tools.pdf.ShapeDrawingAnnotation

| [Class] `com.pdf_tools.pdf.ShapeDrawingAnnotation`          |
| ----------------------------------------------------------- |
| Removed. See [Annotations](./java-interface.mdx#annotations). |

#### com.pdf_tools.pdf.SquareAnnotation

| [Class] `com.pdf_tools.pdf.SquareAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.RectangleAnnotation`                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Changed base class to class [`DrawingAnnotation`](#compdf_toolspdfdrawingannotation). See [Annotations](./java-interface.mdx#annotations).New method `static PolylineAnnotationcreate(pdf.Document targetDocument ,geometry.real.Rectangle boundingBox, pdf.content.Stroke stroke, pdf.content.Fill fill)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `pdf.content.Fill getFill()`. See [DrawingAnnotation](#compdf_toolspdfdrawingannotation) for inherited changes. |

#### com.pdf_tools.pdf.SquigglyAnnotation

| [Class] `com.pdf_tools.pdf.SquigglyAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Squiggly` |
| --------------------------------------------------------------------------------------------------------------- |
| See [HighlightAnnotation](#compdf_toolspdfhighlightannotation) for inherited changes.                           |

#### com.pdf_tools.pdf.StampAnnotation

| [Class] `com.pdf_tools.pdf.StampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Stamp` |
| --------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes.                           |

#### com.pdf_tools.pdf.StickyNoteAnnotation

| [Class] `com.pdf_tools.pdf.StickyNoteAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.StickyNote`                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static StickyNotecreate(pdf.Document targetDocument, geometry.real.Point topleft, String content, pdf.content.Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes. |

#### com.pdf_tools.pdf.StrikeThroughAnnotation

| [Class] `com.pdf_tools.pdf.StrikeThroughAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.StrikeThrough` |
| ------------------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes.                                   |

#### com.pdf_tools.pdf.TextInsertAnnotation

| [Class] `com.pdf_tools.pdf.TextInsertAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextInsert` |
| ------------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes.                             |

#### com.pdf_tools.pdf.TextMarkupAnnotation

| [Class] `com.pdf_tools.pdf.TextMarkupAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextMarkup` |
| ------------------------------------------------------------------------------------------------------------------- |
| See [MarkupAnnotation](#compdf_toolspdfmarkupannotation) for inherited changes.                                     |

#### com.pdf_tools.pdf.TextStampAnnotation

| [Class] `com.pdf_tools.pdf.TextStampAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextStamp`                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static TextStampcreate(pdf.Document targetDocument, geometry.real.Point topleft, Double height, TextStampType type, String content)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [`StampAnnotation`](#compdf_toolspdfstampannotation) for inherited changes. |

#### com.pdf_tools.pdf.TextStampType

| [Enum.] `com.pdf_tools.pdf.TextStampType` → `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.TextStampType` |
| ---------------------------------------------------------------------------------------------------------------- |
|                                                                                                                  |

#### com.pdf_tools.pdf.UnderlineAnnotation

| [Class] `com.pdf_tools.pdf.UnderlineAnnotation`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.annotations.Underline` |
| ----------------------------------------------------------------------------------------------------------------- |
| See [TextMarkupAnnotation](#compdf_toolspdftextmarkupannotation) for inherited changes.                           |

### pdf.content namespace

#### com.pdf_tools.pdf.BlendMode

| [Enum.] `com.pdf_tools.pdf.BlendMode` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.BlendMode` |
| ---------------------------------------------------------------------------------------------------- |
|                                                                                                      |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedGrayColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedGrayColorSpace`                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedRgbColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedRgbColorSpace`                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedCmykColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.CalibratedCmykColorSpace`                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.ColorSpace

| [Class] `com.pdf_tools.pdf.ColorSpace`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ColorSpace`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getComponents` → `getComponentCount`.Removed method `getType`.Removed method `getName`.New method `static ColorSpace createProcessColorSpace(pdf.Document targetDocument, pdf.content.ProcessColorSpaceType type)`New method `static ColorSpace copy(pdf.Document targetDocument, ColorSpace colorSpace)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.ColorSpaceType

| [Enum.] `com.pdf_tools.pdf.ColorSpaceType`                                  |
| --------------------------------------------------------------------------- |
| Removed. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.Content

| [Class] `com.pdf_tools.pdf.Content`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Content`                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.ContentElement

| [Class] `com.pdf_tools.pdf.ContentElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentElement`                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Content elementcopy(pdf.Document targetDocument, ContentElement contentElement)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.ContentExtractor

| [Class] `com.pdf_tools.pdf.ContentExtractor`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentExtractor`                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.ContentGenerator

| [Class] `com.pdf_tools.pdf.ContentGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ContentGenerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Changed method `void paintPath(Path path, Paint fill, StrokeParams stroke, boolean intersectClipping)` → `void paintPath(Path path, Fill fill, Stroke stroke)`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations).Changed behavior of methods `paintImage` and `paintImageMask`: Value `null` for second argument of type `Rectangle` is not supported anymore.New method `void clipWithPath(pdf.content.Path path, pdf.content.InsideRule InsideRule)`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path) and [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations).New method `void clipWithText(pdf.content.Text text)`. See [Path and text clipping operations](./java-interface.mdx#path-and-text-clipping-operations). |

#### com.pdf_tools.pdf.DeviceColorSpaceType

| [Enum.] `com.pdf_tools.pdf.DeviceColorSpaceType` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ProcessColorSpaceType` |
| --------------------------------------------------------------------------------------------------------------------------- |
| Renamed enum value `R_G_B` → `RGB`.Renamed enum value `C_M_Y_K` → `CMYK`.                        |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceGrayColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceGrayColorSpace`                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceCmykColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceCmykColorSpace`                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceRgbColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.DeviceRgbColorSpace`                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.FillParams

| [Struct → class] `com.pdf_tools.pdf.FillParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Fill`                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed constructor `FillParams(Paint paint, InsideRule fillRule)`.Renamed methods `getFillRule` and `setFillRule` → `getInsideRule1` / `setInsideRule`. See [Separate inside rule from path](./java-interface.mdx#separate-inside-rule-from-path).New constructor `Fill(Paint paint)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.Font

| [Class] `com.pdf_tools.pdf.Font`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Font`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getCharWidth` → `getCharacterWidth`.New method `static Fontcreate(pdf.Document targetDocument, sys.Stream stream, boolean embedded)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static FontcreateFromSystem(pdf.Document targetDocument, String family, String style, boolean embedded)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.Group

| [Class] `com.pdf_tools.pdf.Group` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Group`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Group create(pdf.Document targetDocument, geometry.real.Size size)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static Group createFromPage(pdf.Document targetDocument, pdf.Page page, pdf.PageCopyOptions copyOptions)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.GroupElement

| [Class] `com.pdf_tools.pdf.GroupElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.GroupElement`                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static GroupElement copyWithoutContent(pdf.Document targetDocument, GroupElement groupElement)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes. |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.IccBasedColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.IccBasedColorSpace`                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Method `static pdf.content.IccBasedColorSpace create(pdf.Document targetDocument, sys.Stream profile)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). Substitutes the removed enumColorSpaceType. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.Image

| [Class] `com.pdf_tools.pdf.Image` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Image`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Removed method `getWidth`. Replaced by new method `getSize`.Removed method `getHeight`. Replaced by new method `getSize`.New method `static Imagecreate(pdf.Document targetDocument, sys.Streamstream)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `geometry.integer.Size getSize()`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |

#### com.pdf_tools.pdf.ImageElement

| [Class] `com.pdf_tools.pdf.ImageElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageElement` |
| --------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes.                               |

#### com.pdf_tools.pdf.ImageMask

| [Class] `com.pdf_tools.pdf.ImageMask`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageMask`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Removed method `getWidth`. Replaced by new method `getSize`.Removed method `getHeight`. Replaced by new method `getSize`.New method `static ImageMask create(pdf.Document targetDocument, sys.Stream stream)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `geometry.integer.Size getSize()`. See [Image size and image mask size](./java-interface.mdx#image-size-and-image-mask-size). |

#### com.pdf_tools.pdf.ImageMaskElement

| [Class] `com.pdf_tools.pdf.ImageMaskElement` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ImageMaskElement` |
| ------------------------------------------------------------------------------------------------------------------ |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes.                                        |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.IndexedColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.IndexedColorSpace`                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.InsideRule

| [Enum.] `com.pdf_tools.pdf.InsideRule` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.InsideRule` |
| ------------------------------------------------------------------------------------------------------ |
|                                                                                                        |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.LabColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LabColorSpace`                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.LineCapStyle

| [Class] `com.pdf_tools.pdf.LineCapStyle` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LineCapStyle` |
| ---------------------------------------------------------------------------------------------------------- |
|                                                                                                            |

#### com.pdf_tools.pdf.LineJoinStyle

| [Enum.] `com.pdf_tools.pdf.LineJoinStyle` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.LineJoinStyle` |
| ------------------------------------------------------------------------------------------------------------ |
|                                                                                                              |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.NChannelColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.NChannelColorSpace`                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace).Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.Paint

| [Class] `com.pdf_tools.pdf.Paint`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Paint`                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Paint create(pdf.Document targetDocument, pdf.content.ColorSpace colorSpace, double[] color, pdf.content.Transparency transparency)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods) and [Unified paint creation](./java-interface.mdx#unified-paint-creation).  |

#### com.pdf_tools.pdf.Path

| [Class] `com.pdf_tools.pdf.Path`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Path`                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Changed constructor `Path(FillRule rule)` → `Path()`. See [Separate insiderule from path](./java-interface.mdx#separate-inside-rule-from-path). |

#### com.pdf_tools.pdf.PathElement

| [Class] `com.pdf_tools.pdf.PathElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.PathElement` |
| ------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes.                             |

#### com.pdf_tools.pdf.PathGenerator

| [Class] `com.pdf_tools.pdf.PathGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.PathGenerator` |
| ----------------------------------------------------------------------------------------------------------- |
|                                                                                                             |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.content.SeparationColorSpace

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.content.SeparationColorSpace`                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extends [`pdf.content.ColorSpace`](#compdf_toolspdfcolorspace). Substitutes the removed enum `ColorSpaceType`. See [Color space classes](./java-interface.mdx#color-space-classes). |

#### com.pdf_tools.pdf.ShadingElement

| [Class] `com.pdf_tools.pdf.ShadingElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.ShadingElement` |
| ------------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes.                                   |

#### com.pdf_tools.pdf.StrokeParams

| [Struct → class] `com.pdf_tools.pdf.StrokeParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Stroke`                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed constructor `StrokeParams(Paint paint, double lineWidth, LineCapStyle lineCapStyle, LineJoinStyle lineJoinStyle, double[] dashArray, double dashPhase, double miterLimit)`.New constructor `Stroke(Paint paint, double lineWidth)`.See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.Text

| [Class] `com.pdf_tools.pdf.Text`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Text`                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Textcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.TextElement

| [Class] `com.pdf_tools.pdf.TextElement`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextElement` |
| ------------------------------------------------------------------------------------------------------- |
| See [ContentElement](#compdf_toolspdfcontentelement) for inherited changes.                             |

| [Class] `com.pdf_tools.pdf.TextFragment`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextFragment`                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Renamed method `getUnicodeString` → `getText`. |

#### com.pdf_tools.pdf.TextGenerator

| [Class] `com.pdf_tools.pdf.TextGenerator`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.content.TextGenerator`                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed method `setRendering`. Replaced by methods `setFill` and `setStroke`. See [Text generator](./java-interface.mdx#text-generator).Renamed method `setCharSpacing` → `setCharacterSpacing`. See [Renaming](./java-interface.mdx#renaming).New methods `Paint getFill()`and `void setFill(PaintFill)`.New methods `Stroke getStroke()` and `void setStroke(Stroke Stroke)`. |

#### com.pdf_tools.pdf.TransparencyParams

| [Struct → Class] `com.pdf_tools.pdf.TransparencyParams` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.Transparency`                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  Removed constructor `TransparencyParams(BlendMode blendMode, double constAlpha)`.Renamed methods `getConstAlpha` and `setConstAlpha`→ `getAlpha` / `setAlpha`.New constructor `Transparency(double alpha)`. |

#### com.pdf_tools.pdf.UngroupingSet

| [Enum.] `com.pdf_tools.pdf.UngroupingSet` → `com.pdf_tools.fourheights.pdftoolbox.pdf.content.UngroupingSelection` |
| ------------------------------------------------------------------------------------------------------------------ |
|                                                                                                                    |

### pdf.forms namespace

#### com.pdf_tools.pdf.CheckBoxField

| [Class] `com.pdf_tools.pdf.CheckBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.CheckBox`                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static CheckBoxcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormField](#compdf_toolspdfformfield) for inherited changes. |

#### com.pdf_tools.pdf.ChoiceField

| [Class] `com.pdf_tools.pdf.ChoiceField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceField` |
| ----------------------------------------------------------------------------------------------------- |
| See [FormField](#compdf_toolspdfformfield) for inherited changes.                                     |

#### com.pdf_tools.pdf.ChoiceItem

| [Class] `com.pdf_tools.pdf.ChoiceItem`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceItem`                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.ChoiceItemList

| [Class] `com.pdf_tools.pdf.ChoiceItemList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ChoiceItemList`                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.ComboBoxField

| [Class] `com.pdf_tools.pdf.ComboBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ComboBox`                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ComboBoxcreate(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ChoiceField](#compdf_toolspdfchoicefield) for inherited changes. |

#### com.pdf_tools.pdf.CombTextField

| [Class] `com.pdf_tools.pdf.CombTextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.CombTextField`                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  New method `static CombTextFieldcreate(pdf.Document targetDocument, int maxLength)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New methods `int getMaxLength()` and `void setMaxLength(int MaxLength)`. See [MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields. See [TextField](#compdf_toolspdftextfield) for inherited changes. |

#### com.pdf_tools.pdf.FormField

| [Class] `com.pdf_tools.pdf.FormField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.Field` |
| --------------------------------------------------------------------------------------------- |
| See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes.                     |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FormFieldCopyStrategy

| [Enum.] `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FormFieldCopyStrategy`                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`COPY``FLATTEN``REMOVE``COPY_AND_UPDATE_WIDGETS`Substitutes the removedCopyOption. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.FormFieldNode

| [Class] `com.pdf_tools.pdf.FormFieldNode`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FieldNode`                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static FieldNode copy(pdf.Document targetDocument, FieldNode fieldNode)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.FormFieldNodeMap

| [Class] `com.pdf_tools.pdf.FormFieldNodeMap`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.FieldNodeMap`                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.GeneralTextField

| [Class] `com.pdf_tools.pdf.GeneralTextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.GeneralTextField`                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  New method `static GeneralTextField create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New methods `Integer getMaxLength()` and `void setMaxLength(Integer MaxLength)`. See [MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields). See [TextField](#compdf_toolspdftextfield) for inherited changes. |

#### com.pdf_tools.pdf.ListBoxField

| [Class] `com.pdf_tools.pdf.ListBoxField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.ListBox`                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ListBox create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [ChoiceField](#compdf_toolspdfchoicefield) for inherited changes. |

#### com.pdf_tools.pdf.PushButtonField

| [Class] `com.pdf_tools.pdf.PushButtonField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.PushButton` |
| -------------------------------------------------------------------------------------------------------- |
|                                                                                                          |

#### com.pdf_tools.pdf.RadioButton

| [Class] `com.pdf_tools.pdf.RadioButton`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButton`                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.RadioButtonField

| [Class] `com.pdf_tools.pdf.RadioButtonField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButtonGroup`                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed methods `getCanToggleOff` and `setCanToggleOff`.New method `static RadioButtonGroup create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormField](#compdf_toolspdfformfield) for inherited changes. |

#### com.pdf_tools.pdf.RadioButtonList

| [Class] `com.pdf_tools.pdf.RadioButtonList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.RadioButtonList`                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.SignatureField

| [Class] `com.pdf_tools.pdf.SignatureField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SignatureField`                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Changed type of method `getDate` from `java.util.Calendar` to `java.time.OffsetDateTime`. See [OffsetDateTime](./java-interface.mdx#offsetdatetime). |

#### com.pdf_tools.pdf.SignatureFieldList

| [Class] `com.pdf_tools.pdf.SignatureFieldList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SignatureFieldList`                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.SubForm

| [Class] `com.pdf_tools.pdf.SubForm`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.SubForm`                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static SubForm create(pdf.Document targetDocument)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes. |

#### com.pdf_tools.pdf.TextField

| [Class] `com.pdf_tools.pdf.TextField`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.TextField`                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed methods `getMaxLength` and `setMaxLength`. See[MaxLength in text fields](./java-interface.mdx#maxlength-in-text-fields). See [FormFieldNode](#compdf_toolspdfformfieldnode) for inherited changes. |

#### com.pdf_tools.pdf.Widget

| [Class] `com.pdf_tools.pdf.Widget`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.Widget`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed inheritance from class `Annotation`. See [Annotations](./java-interface.mdx#annotations).Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).Duplicated method `geometry.real.Rectangle getBoundingBox()` from former base class `Annotation`.Duplicated method `boolean getHidden()`from former base class `Annotation`.Duplicated method `boolean getNoPrint()` from former base class `Annotation`. |

#### com.pdf_tools.pdf.WidgetList

| [Class] `com.pdf_tools.pdf.WidgetList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.forms.WidgetList`                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

### pdf.navigation namespace

#### com.pdf_tools.pdf.Destination

| [Class] `com.pdf_tools.pdf.Destination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.Destination`                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.DirectDestination

| [Class] `com.pdf_tools.pdf.DirectDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.DirectDestination` |
| ---------------------------------------------------------------------------------------------------------------------- |
| See [Destination](#compdf_toolspdfdestination) for inherited changes.                                                  |

#### com.pdf_tools.pdf.EmbeddedPdfLink

| [Class] `com.pdf_tools.pdf.EmbeddedPdfLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.EmbeddedPdfLink`                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static EmbeddedPdfLink create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, pdf.FileReference fileReference)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).SeeLinkfor inherited changes. |

#### com.pdf_tools.pdf.FitHeightDestination

| [Class] `com.pdf_tools.pdf.FitHeightDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitHeightDestination`                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitHeightDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |

#### com.pdf_tools.pdf.FitPageDestination

| [Class] `com.pdf_tools.pdf.FitPageDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitPageDestination`                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitPageDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes.  |

#### com.pdf_tools.pdf.FitRectangleDestination

| [Class] `com.pdf_tools.pdf.FitRectangleDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitRectangleDestination`                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitRectangleDestination create(pdf.Document targetDocument, pdf.Page page, geometry.real.Rectangle rectangle)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |

#### com.pdf_tools.pdf.FitWidthDestination

| [Class] `com.pdf_tools.pdf.FitWidthDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.FitWidthDestination`                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static FitWidthDestination create(pdf.Document targetDocument, pdf.Page page, boolean fitActualContent)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |

#### com.pdf_tools.pdf.InternalLink

| [Class] `com.pdf_tools.pdf.InternalLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.InternalLink` |
| ------------------------------------------------------------------------------------------------------------ |
| See [Link](#compdf_toolspdflink) for inherited changes.                                                      |

#### com.pdf_tools.pdf.Link

| [Class] `com.pdf_tools.pdf.Link`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.Link`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed inheritance from class `Annotation`. See [Annotations](./java-interface.mdx#annotations).Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static Link copy(pdf.Document targetDocument, Link link)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).Duplicated method `geometry.real.Rectangle getBoundingBox()` from former base class `Annotation`.Duplicated method `boolean getHidden()` from former base class `Annotation`.Duplicated method `boolean getNoPrint()` from former base class `Annotation`. |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LinkList

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LinkList` |
| ---------------------------------------------------------------------- |
| A list that contains [Link](#compdf_toolspdflink) objects.             |

#### com.pdf_tools.pdf.LocationZoomDestination

| [Class] `com.pdf_tools.pdf.LocationZoomDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.LocationZoomDestination` |
| ---------------------------------------------------------------------------------------------------------------------------------- |

| 
Removed constructor. See [Constructors](./java-interface.mdx#constructors).
New method `static ZoomDestination create(pdf.Document targetDocument, pdf.Page page, Double left, Double top,Double zoom)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [DirectDestination](#compdf_toolspdfdirectdestination) for inherited changes. |

#### com.pdf_tools.pdf.NamedDestination

| [Class] `com.pdf_tools.pdf.NamedDestination`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestination`                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static NamedDestination create(pdf.Document targetDocument, String name, DirectDestination target)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Destination](#compdf_toolspdfdestination) for inherited changes. |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestinationCopyStrategy

| [Enum] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.NamedDestinationCopyStrategy`                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------- |
| Values:`COPY` `RESOLVE` Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineCopyOptions

| [Class] `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineCopyOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  constructor `OutlineCopyOptions()`Methods `pdf.navigation.NamedDestinationCopyStrategy getNamedDestinations()` and `void setNamedDestinations(pdf.navigation.NamedDestinationCopyStrategy NamedDestinations)`Default: `NamedDestinationCopyStrategy.COPY`Methods `boolean getCopyLogicalStructure()` and `void setCopyLogicalStructure(boolean CopyLogicalStructure)`Default: `true` Substitutes the removed `CopyOption`. See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.OutlineItem

| [Class] `com.pdf_tools.pdf.OutlineItem`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed).New method `static OutlineItem create(pdf.Document targetDocument, String title, Destination Destination)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods).New method `static OutlineItem copy(pdf.Document targetDocument, OutlineItem outlineItem, OutlineCopyOptions options)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Copy options](./java-interface.mdx#copy-options). |

#### com.pdf_tools.pdf.OutlineItemLists

| [Class] `com.pdf_tools.pdf.OutlineItemList`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.OutlineItemList`                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Removed implementation of the `AutoCloseable` interface. See [Removal of AutoCloseable implementation](./java-interface.mdx#autocloseable-implementation-removed). |

#### com.pdf_tools.pdf.PageDisplay

| [Struct] `com.pdf_tools.pdf.PageDisplay` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.PageDisplay`                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  New base class `com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase`. See [Structs extend NativeBase](./java-interface.mdx#structs-extend-nativebase).Changed default value of `fieldcontinuous` from `true` to `false`. |

#### com.pdf_tools.pdf.PageLayout

| [Enum.] `com.pdf_tools.pdf.PageLayout` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.PageLayout` |
| --------------------------------------------------------------------------------------------------------- |
|                                                                                                           |

#### com.pdf_tools.pdf.ViewerNavigationPane

| [Enum.] `com.pdf_tools.pdf.ViewerNavigationPane` → `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.ViewerNavigationPane` |
| ----------------------------------------------------------------------------------------------------------------------------- |
|                                                                                                                               |

#### com.pdf_tools.pdf.ViewerSettings

| [Class] `com.pdf_tools.pdf.ViewerSettings`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.ViewerSettings`                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New method `static ViewerSettings copy(pdf.Document targetDocument, ViewerSettings viewerSettings)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). |

#### com.pdf_tools.pdf.WebLink

| [Class] `com.pdf_tools.pdf.WebLink`→ `com.pdf_tools.fourheights.pdftoolbox.pdf.navigation.WebLink`                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  Removed constructor. See [Constructors](./java-interface.mdx#constructors).New method `static WebLink create(pdf.Document targetDocument, geometry.real.Rectangle boundingBox, String uri)`. See [Creation and copying methods](./java-interface.mdx#creation-and-copying-methods). See [Link](#compdf_toolspdflink) for inherited changes. |

## sys namespace

#### com.pdf_tools.FileStream

| [Class] `com.pdf_tools.FileStream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.FileStream` |
| ----------------------------------------------------------------------------------------- |
|                                                                                           |

#### com.pdf_tools.MemoryStream

| [Class] `com.pdf_tools.MemoryStream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.MemoryStream` |
| --------------------------------------------------------------------------------------------- |
|                                                                                               |

#### com.pdf_tools.Stream

| [Class] `com.pdf_tools.Stream`→ `com.pdf_tools.fourheights.pdftoolbox.sys.Stream` |
| --------------------------------------------------------------------------------- |
|                                                                                   |

---

## Use the source code migration script for the PDF Toolbox SDK

You can use the [PDF Toolbox SDK Python script](https://www.pdf-tools.com/docs/pdf-toolbox-sdk/migration-guide/use-migration-script/3hto4h.py) (`3hto4h.py`) to automate the major part of source code migration from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

:::note Before you start
Python 3.4 or later is required.
:::

1. Back up your source code, if necessary.
2. Execute the [script](https://www.pdf-tools.com/docs/pdf-toolbox-sdk/migration-guide/use-migration-script/3hto4h.py), where `‹dir›` is the root directory of your source tree:

```
python 3hto4h.py ‹dir›
```

3. The script iterates through files contained in the given directory and all its subdirectories (recursively), and processes the following file types:

- \*.c, \*.cpp, \*.cxx
- \*.h, \*.hpp, \*.hxx
- \*.java
- \*.cs

Each matching file is processed in-place.
The processing consists solely of regular expression substitutions, which fall into two categories:

- Source code replacement
- Marking of code that needs attention by appending a trailing comment:

```
... //TODO 3H->4H: ‹message›
```

4. You can switch off the code marking by executing the script with the `-m` option:

```
python 3hto4h.py -m ‹dir›
```

:::note
The substitutions done in this script **do not completely migrate all source code**. Compiler errors indicate code that needs manual migration.  
In some situations, the script can falsely replace code that has no connection to the 3-Heights® PDF Toolbox API. Such changes must be undone.

The `//TODO 3H->4H` markers help to locate code that could not be migrated completely or behavioral changes that need manual implementation.
:::

---

## About the PDF Toolbox SDK

The PDF Toolbox SDK is a native library with interfaces for .NET, Java, and C for creating, extracting, assembling, and modifying PDF documents.

---

## Key features

import KeyFeatures from './_key-features.mdx';

## Document model

import DocModel from './_document-model.mdx';

## Thread safety

import ThreadSafety from './_thread-safety.mdx';

## PDF graphics model

import GraphicsModel from './_graphics-model.mdx';

---

## _document Model

The document model of the {props.name} consists of two different types of objects:

- **Structure objects**: define the structure of the document. These objects include `Document`, `Page`, and `Content`.
- **Graphics resources**: used to draw content with a [ContentGenerator](#generator-objects). Examples are `Image`, `Font`, and `ColorSpace`.

All objects in the document model are bound to a specific document. They can only be used in the context of the document for which they were created. The objects of the document model are all stateless. Where a stateful interface is required, it is provided by an external generator or extractor, which is not considered part of the document model.

The PDF Toolbox SDK does not allow in-place modification of documents. Instead, the content is copied into a new document, while performing the necessary changes.

To copy objects from a source document into a target document, you call the object’s static `Copy` method with the target document as first argument. This means you can process very large files without consuming too much memory. The content of the input document is only read on demand and any modifications can be directly stored in the output file.

To provide a uniform interface, operations are divided into two steps:
1. [Create (or copy) the object](#create-the-object)
2. [Use the object](#use-the-object)

This separation means there are multiple variants for both steps, without having a “combinatorical explosion” of methods.

#### Create the object
The object is created in the target document or copied from the source document to the target document.
After creation, the object is associated with the document, but not yet used. This means that copying or creating an object may change the size of the target file. However, logically, the PDF is still unchanged.

For example, these methods can be used to create an object:
- `Page.Create`
- `Font.Create`
- `Page.Copy`
- `PageList.Copy`
- `ColorSpace.Copy`
- `Metadata.Copy`
- `ContentElement.Copy`

#### Use the object
The associated object can then be used in the target document.
This second step is often more lightweight than the first step, since all the necessary copying of objects is already done.

For example, these methods of the `ContentGenerator` generator object are used:
- `PaintImage`
- `PaintGroup`
- `AppendContentElement`
or the `PageList.Add` method.

### Generator objects
Some objects in a PDF consist of a list or stream of operations that operate on an internal state:
- Content streams
- Text objects
- Path objects

Since all data objects in the PDF Toolbox SDK are stateless, a (simplified) stateful interface is provided by the generator interfaces:

- Content objects can be modified with a `ContentGenerator`.
- Path objects can be modified with a `PathGenerator`.
- Text objects can be modified with a `TextGenerator`.

Generator objects must always be closed explicitly before the generated object can be used.

### Garbage collection and closing objects
Every interface object is considered to be a resource that needs to be closed after use. Most objects are closed automatically, at the latest when the owning document is closed (in C# and Java), possibly earlier by the garbage collector.

In addition to `Document` objects, the [generator objects](#generator-objects) `ContentGenerator`, `PathGenerator`, and `TextGenerator` must be closed. Otherwise, the generated objects are incomplete.

---

## _graphics Model

### Coordinate system
PDF coordinates are measured from bottom to top, unlike many other coordinate systems used in IT.

For the sake of simplicity, all coordinates used in the PDF Toolbox SDK are normalized such that the point (0,0) denotes the lower left corner of the visible page (crop box).
The internal `Rotate` attribute of a PDF page is not exposed at the API. Instead, all coordinates are assumed to refer to the already rotated page.

### Affine transformations
Affine transformations can be used to rotate, move, scale, or otherwise, skew any page content.

Transformations always affect the coordinate system as a whole. All following graphics operations are executed in
the transformed coordinate system, including additional transformations.

This means that the ordering of how transformations are applied is important.

---

## _key Features

### Document generation
The PDF Toolbox SDK lets you create PDF files, defining structure at document level and content at page level.

#### Create PDF document definition
You can create a new document from scratch, determining the pages in the document tree, adding form fields, and adding outline items.

- Create pages
- Create form fields:
  - General text fields and comb text fields
  - Check boxes
  - Radio button groups
  - List boxes
  - Combo boxes
- Create new outline items and insert them at any position in the tree
- Destinations: Named and direct destinations in the same document
- Configure viewer settings

#### Create content at page level

- Create new PDF content from scratch
- Apply content to existing pages

**Determine colors**
- Device colors: RGB, CMYK, and grayscale
- ICC color profiles
- Transparency: alpha and blend mode

**Add trace paths**
- Single and multi-segment lines
- Rectangle, circle, Bezier curves, ellipse, arc, pie
- Filling, stroking, clipping, and combinations thereof
- Line width, cap, join, dash array, dash phase, and miter limit
- Inside rule: nonzero winding rule, even/odd rule

**Add text**
- Font size, character spacing, word spacing
- Horizontal scaling, leading, rise
- Enables simple text layouting
- Standard PDF fonts, installed fonts
- Font metrics: italic angle, ascent, descent, cap height, character width
- Unicode characters
- Text stroke: line width, line join, and dashes
- Fill and stroke text, invisible text
- Use text as clipping path

**Add images**
- Bi-level: CCITT G3, G3 2D and G4, Flate, LZW, Packbits, uncompressed
- 4 bit and 8 bit grayscale: Flate, LZW, Packbits, JPEG and JPEG-6 (8 bit only), uncompressed
- RGB: Flate, JPEG and JPEG-6, LZW, Packbits, uncompressed

**Add transformations**
- Translation
- Scaling
- Skewing (horizontal, vertical)
- Rotation

#### Create annotations and links
You can add multiple annotation types such as text, stamps, drawings, and text revision marks to the PDF pages. You can add internal links such as section references and external links to specific web pages or embedded files.

- Document-internal links
- Web links
- Links to embedded PDFs
- File attachment annotations
- Free text annotation
- Sticky note annotation
- Text stamp annotation
- Custom stamp annotation
- Circle annotation
- Square annotation
- Line annotation
- Poly line annotation
- Polygon annotation
- Ink annotation (pen drawing)
- Highlight annotation
- Underline and squiggly underline annotation
- Strike-through annotation

### Document modification
The PDF Toolbox SDK lets you edit PDF files, deleting objects, adding markup annotations, deleting or changing field values.

#### Edit page content
- Selectively delete content elements (without tagging and layers)
- Transform content elements geographically (without tagging and layers)

#### Edit annotations
- Web link annotation target URIs
- Markup annotation location, creation and modification date, subject, author, content

#### Edit form fields
- Delete fields and modify field values for:
  - General text fields and comb text fields
  - Check boxes
  - Radio button groups
  - List boxes
  - Combo boxes

### Document extraction
The PDF Toolkit SDK lets you extract data and text from PDF files.

#### Extract data from document and page level
You can extract specific data from PDF documents, either at document or page level. Information you can extract includes metadata, page content, encryption settings, and information about embedded files.

- Document information entries: title, author, subject, keywords, creator, producer, creation date, modification date
- Document XMP metadata
- Document encryption settings
- Embedded files
- Page bounding boxes: media box, crop box, bleed box, trim box, art box
- Page XMP metadata
- Outline item tree: Tree structure, item title, expanded/collapsed
- Destinations: Named and direct destinations in the same document
- Viewer settings

####  Extract content
- Page and group content elements, including:
    - Bounding box
    - Affine transformation
          As either of the following:
        - Group element
        - Image element
    - Width and height in pixel
    - Bits per component
    - Color space
- Image mask element
  - Width and height in pixel
  - Paint for filling the mask
- Path element
  - Alignment box
  - Subpaths and subpath segments
  - Fill parameters including paint and fill rule
  - Stroke parameters including line paint and line style
- Shading element
- Text element
  - Text fragments
    - Bounding box
    - Affine transformation
    - Unicode string
    - Fill parameters, including paint and fill rule
    - Stroke parameters, including line paint and line style
    - Font size, character spacing, word spacing, horizontal scaling, and text rise

####  Extract annotations
- Annotations: location
- Markup annotation: type, location, creation/modification date, subject, author, content
- Custom stamp annotations: appearance
- Text markup annotations: markup area
- Link annotations: location, target destination or URI, active link area
- Signature fields: name, location, reason, contact info, date, visibility

#### Extract AcroForm form fields

- Form field identifiers, export names, and user names, including form field hierarchy
- Form field export and display content of:
    - Push buttons
    - Check boxes
    - Radio button groups
    - General text fields and comb text fields
    - List boxes
    - Combo boxess

### Document assembly
The PDF Toolbox SDK lets you assemble PDF files from existing PDF files.

#### Assemble PDF files
- Copy pages from existing PDFs
- Copy annotations, form fields, links, logical structure, destinations, outlines, and layers
- Flatten annotations, form fields, and signatures
- Optimize resources
- Crop and rotate pages
- Compose content: overlays, underlays, stamps, transformations
- Add encryption: user password, owner password, permissions
- Copy and modify document metadata
- Copy and modify page metadata
- Add embedded files and associated files
- Get and set OpenAction destination
- Merge a PDF and an FDF
- Separate markup annotations into an FDF

---

## _thread Safety

The PDF Toolbox SDK is generally thread-­safe. However, a **document may only be accessed in one thread concurrently, including all sub­objects.**
Almost all objects are directly or indirectly associated with a document.

:::note
Methods that copy from a source to a target document have to access both documents. 

The thread safety rules **apply both to the target document and the source document**. This means that copying from the same source document concurrently is not allowed.
:::

### Garbage collection and finalizer
Object finalization is thread-­safe. 

:::caution
**The finalizer of the `Document` is not thread-­safe regarding access to its subobjects.**
:::

Subobjects do not retain their associated document object. If all references to an open document go out of scope, the document finalizer is eventually run and the document is closed.

:::danger
Explicitly accessing (or even closing) any subobject while the document finalizer is running is not safe!
:::

---

## Release notes for the PDF Toolbox SDK

## Version 4.4.11

27 June 2025

### Added

- You can now call the [GetResolution](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask_GetResolution.htm) method of the [ImageMask](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask.htm) class.

## Version 4.4.10

19 June 2025

### Added

- You can now call the [GetResolution](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_GetResolution.htm) method of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) class.

## Version 4.4.9

13 March 2025

### Fixed

- Prior to this release, radio buttons were improperly copied to the output document.
- Fixed a regression that caused decryption to fail for encrypted PDFs using a specific encryption algorithm.
- Improved handling of faulty PostScript string syntax to ensure correct parsing of ToUnicode maps.

## Version 4.4

17 October 2023

### Added

- You can now call the [Extract](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/M_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_Extract.htm) method of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) and [ImageMask](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ImageMask.htm) classes to extract an image in [various output formats](../use/extract/#extract-images).
- Retrieve stored image samples by accessing the [Samples](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image_Samples.htm) property of the [Image](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_Image.htm) class.
- As of this update, you can use [memory streams](https://api-reference.pdf-tools.com/toolsdk/4.4/cdoc/_pdf_toolbox___ptx_sys_8h.html#a585bc83936fa48f1b6364327c0da4f01) with the C API.
- Check if a PDF document is linearized by accessing the [IsLinearized](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Document_IsLinearized.htm) property of the [Document](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Document.htm) class.
- Retrieve page labels as alternate page numbers by accessing the [PageLabel](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/P_PdfTools_FourHeights_PdfToolbox_Pdf_Page_PageLabel.htm) property of the [Page](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Page.htm) class.

### Fixed

- Fixed an issue that could cause the PDF Toolbox SDK to terminate unexpectedly when using the [ContentExtractor](https://api-reference.pdf-tools.com/toolsdk/4.4/dotnet/html/T_PdfTools_FourHeights_PdfToolbox_Pdf_Content_ContentExtractor.htm) class to iterate through the content of a page.

## Version 4.3

20 July 2023

### Updated C API ZIP archive layout

- The C API ZIP archive directory layout has been updated (see [Install](install/README.mdx)).

### Updated Java API ZIP archive layout

- The Java API ZIP archive directory layout has been updated (see [Install](install/README.mdx)).

### Linux

- The minimum required glibc version was upgraded from 2.27 to 2.34.

## Version 4.2

15 May 2023

### Pdf.Annotations.TextStamp

- Deprecated static method `createRaw`.
- New static method `create`.

### Pdf.Content.TextFragment (.NET and Java)

- New method `remove`.

### Pdf.Annotations.FreeText

- Changed static method `Create`: Extended with optional `Stroke`.

### Pdf.Annotations.FreeText

- New property `FontSize`.

### Pdf (.NET and Java)

- Changed the following classes to be abstract:
  - `Pdf.Content.ColorSpace`
  - `Pdf.Content.ContentElement`
  - `Pdf.Forms.ChoiceField`
  - `Pdf.Forms.Field`
  - `Pdf.Forms.FieldNode`
  - `Pdf.Forms.TextField`
  - `Pdf.Navigation.Destination`
  - `Pdf.Navigation.DirectDestination`
  - `Pdf.Navigation.Link`

## Version 4.1

28 March 2023

### Pdf.Metadata

- New method `setCreationDate`.

### Pdf.Annotations.Annotation

- New property (get) `Name`.

## Version 4.0

23 January 2023

### Sdk

- Changed behavior of static property `ProducerFullName`. The producer full name is returned instead of the product name.

### Pdf.Content

- New enumeration `FontWeight`.

**Pdf.Content.Font**

- New property (get) `Weight`.

**Pdf.Content.Glyph**

- New property (get) `Width`.

### Pdf.Document

- Changed behavior of static methods `Create` and `CreateWithFdf`. A `ConformanceException` is generated if the conformance level is lower than 1.7 and Unicode passwords are specified.

### Pdf.Permission

- New enumeration items `All` and `None`.

### Sys.MemoryStream (Java only)

- New constructor from an `InputStream`.
- New method `read`.
- New method `readAllBytes`.
- New method `toByteArray`.
- New method `transferFrom`.
- New method `transferTo`.
- Removed all `MemoryStream` constructors accepting "blockSize" as an argument.

### Sys.FileStream (Java only)

- New enumeration `FileStream.Mode`.
- Changed type of the "mode" argument in `FileStream` constructors from `String` to `FileStream.Mode`.

---

## Version 3.10

28 September 2022

### Pdf.Content

- > New class `Subpath`.
- New struct `PathSegment`.
- New enumeration `PathSegmentType`.

### Pdf.Content.Path

- New extension of interface: Now extracted `Path`s are an iterable for contained `Subpath`s.

### Pdf.Document

- New static method `CreateWithFdf` to store markup annotations in a separate FDF document.

## Version 3.8

16 June 2022

### Pdf.Content.ContentGenerator

- Removed errors `IO` and `Corrupt` from `ContentGenerator` constructor.

## Version 3.6

21 April 2022

### Pdf.Annotations.AnnotationList (.NET only)

- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Annotations.MarkupInfoList (.NET only)

- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Content.Text (.NET only)

- Changed method `Add`: Since this method is not supported it is now implemented explicitly.

### Pdf.Content.TextFragment (.NET only)

- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Forms.FieldNodeMap (.NET only)

- Changed methods `Clear` and `Remove`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Forms.RadioButtonList (.NET only)

- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Forms.SignatureFieldList (.NET only)

- Changed methods `Add`, `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Forms.WidgetList (.NET only)

- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.Navigation.LinkList (.NET only)

- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.FileReferenceList (.NET only)

- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

### Pdf.PageList (.NET only)

- Changed methods `Clear`, `Remove` and `RemoveAt`: Since these methods are not supported they are now implemented explicitly.

## Version 3.4

23 February 2022

### Pdf.Content

- New enumeration `WritingMode`.
- New class `Glyph`.

### Pdf.Content.TextFragment

- New extension of interface: Now this is an iterable for contained `Glyph`s.
- New property (get) `Font`

## Version 3.3

26 January 2022

### Pdf.Navigation.WebLink

- Changed error behavior of property setter for `Uri`: An `IllegalArgument` error is generated if the given value is empty.
- Changed error behavior of methods `Create` and `CreateFromQuadrilaterals`: An `IllegalArgument` error is generated if the given `uri` argument is empty.

### Pdf.PageCopyOptions

- Deprecated property `OcgConflictResolution`.

### Pdf.Forms.SignatureField

- New derived classes `DocumentSignature`, `DocMdpSignature`, `DocUrSignature` and `DocumentTimeStamp` to extract properties of digital signatures.
- Replaced property `IsSigned` with derived class `SignedSignatureField`.
- Moved properties `Name` and `Date` to derived class `SignedSignatureField`, because they are only available in signed signature fields.
- Moved properties `Location`, `Reason` and `ContactInfo` to derived class `Signature`, because they are only available in certain types of signed signature fields.

### Pdf.Forms

- New type `MdpPermissions` for the `Permissions` of `DocMdpSignature`.

## Version 3.1

26 November 2021

### Pdf.Content

- New item `All` in enumeration `UngroupingSelection`.

---

## PDF Toolbox SDK for C

The PDF Toolbox SDK for C lets you create PDF files using C.

:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::

## Namespaces, classes, and methods

In most languages, namespaces and classes are used to model the interfaces. The exception is C, where this is modeled with function prefixes and functions operating on handles.

The PDF Toolbox SDK defines all its used types such as handles and enumerations in the `PdfToolbox_Types.h` header file.

Types are named according to the following naming scheme:

```
T‹prefix›_‹name›
```

where `‹prefix›` is a shortened namespace prefix and `‹name›` is the name of the type.

Similarly, the PDF Toolbox SDK defines functions, collected in header files `PdfToolbox_‹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.

## Library initialization

The first method called must be `Ptx_Initialize`. Failing to invoke this function results in undefined behavior.
Similarly, the last method must be `Ptx_Uninitialize`.

Before calling any of the other functions, a license key must be set by calling `Ptx_Sdk_Initialize`.

## Objects

Objects in the C interface are represented by object handles. Some types are disposable, which means that they must be closed by calling `‹prefix›_‹type›_Close`. All other types must be released by calling `‹prefix›_Release`.

### Type casting

The PDF Toolbox SDK uses a hierarchical class hierarchy, 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, a handle of the child type can be casted using a simple C-style cast:

```
(T‹prefix›_‹parentType›*)pChildTypeHandle
```

Upcasting is also possible using a C-style cast. Prior to casting, the child type of the handle can be determined using
the `GetType` function of the parent class:

```
(T‹prefix›_‹parentType›Type) iChildType = ‹prefix›_‹parentType›_GetType(pParentTypeHandle);
```

## Properties

Properties (a C# term) 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 having called a function, an error should be detected as follows:

1. If the function’s return type `isBOOL` or a pointer and the return value `isFALSE` or `NULL`, respectively, then an error may have occurred. Then `Ptx_GetLastError` must be called. If this method returns `ePtx_Error_Success`, no error has occurred and the return value is legitimate.
2. If the function’s return type is other than Boolean or a pointer, then `Ptx_GetLastError` must be called. If this method returns `ePtx_Error_Success`, then no error has occurred.

More information about the error can be acquired from `PtxGetLastErrorMessage`.

## Strings

All functions involving strings are provided in two different flavors:

- UTF-16 function with suffix W, using `WCHAR` as parameter type.
- Multi-byte character set function with suffix A, using `char` as parameter type. The concrete character set that is 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 effective function names with suffix, there’s a macro without suffix for each function pair.
It either resolves to the W variant (if `_UNICODE` is defined), or to the A variant (if `_UNICODE` is not defined).

**Example: Signature of an API string property setter, where `‹String›` stands for the property’s name**

```
// 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 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, the function has to be called with `NULL` as buffer argument.
Calling the function with a buffer size that is too small results in an error.

Multi-byte character set functions (with suffix A) that return a string can fail to encode the string in the current operating systems’ encoding. In case of such a failure, the return value is 0 and no error code is set.
To prevent such failures, you should use the UTF-16 (W) functions on Windows or use operating systems with a Unicode code page.

**Example: Signature and usage of an API string property getter (Error handling is omitted)**

```
size_t Ptx_Sdk_GetVersionA(char* pBuffer, size_t nBufferSize);
```

```
size_t nBufferSize = Ptx_Sdk_GetVersionA(NULL, 0);
char* pBuffer = malloc(nBufferSize * sizeof char);
nBufferSize = Ptx_Sdk_GetVersionA(pBuffer, nBufferSize);
```

## Streams

Streams are modeled by means of a set of callbacks and a context pointer, grouped in a struct `TPtxSys_StreamDescriptor`.
An implementation for FILE\* is provided in the header file `PdfToolbox_PtxSys.h`. (Search for function `PtxSysCreateFILEStreamDescriptor`.)

## 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, the function has to be called with `NULL` as buffer argument.
Calling the function with a buffer size that is 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. | `ePtx_Error_IllegalState`                                                                  |
| `T‹prefix›_‹eltype›*` `‹prefix›_‹list›_Get(T‹prefix›_‹list›*, int index)` | Get an element of the list.             | `ePtx_Error_IllegalState`, `ePtx_Error_IllegalArgument`, `ePtx_Error_UnsupportedOperation` |
| `BOOL` `‹prefix›_‹list›_Add(T‹prefix›_‹list›*, T‹prefix›_‹eltype›*)`      | Add an element to the end of the list.  | `ePtx_Error_IllegalState`, `ePtx_Error_IllegalArgument`, `ePtx_Error_UnsupportedOperation` |

## Enumerables

Enumerables (C# jargon) are lists that only allow iterating. For every enumerable type `T‹prefix›_‹type›`, an additional iterator type `T‹prefix›_‹type›Iterator` is defined. Every enumerable type provides the following function:

| Function                                                                     | Description                          | Possible errors           |
| ---------------------------------------------------------------------------- | ------------------------------------ | ------------------------- |
| `T‹prefix›_‹type›Iterator*` `‹prefix›_‹type›_GetIterator(T‹prefix›_‹type›*)` | Get an iterator for this enumerable. | `ePtx_Error_IllegalState` |

Every iterator type provides the following functions, where `T‹prefix›_‹eltype›` is the type of the contained
element:

| Function                                                                            | Description                                                                                                                                             | Possible errors           |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `BOOL` `‹prefix›_‹type›Iterator_MoveNext(T‹prefix›_‹type›Iterator*)`                | Move the iterator to the next element. Returns: `1` if the current value is available, `0` if the end has been reached and the current value is `NULL`. | `ePtx_Error_IllegalState` |
| `T‹prefix›_‹eltype›*` `‹prefix›_‹type›Iterator_GetValue(T‹prefix›_‹type›Iterator*)` | Get the current element or NULL if no elements are left.                                                                                                | `ePtx_Error_IllegalState` |

## 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.                                                                                                                                                                                                                                                                                                                       | `ePtx_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. | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`                                                      |
| `int` `‹pre›_‹map›_GetEnd(T‹pre›_‹map›*)`                                            | Get the end position of the map. This position does not 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`.                                                                                                                     | `ePtx_Error_IllegalState`, `ePtx_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`.                                                                        | `ePtx_Error_IllegalState`, `ePtx_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`.                                                                                                                                                                                                      | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`, `ePtx_Error_NotFound` |
| `size_t` `‹pre›_‹map›_GetKeyA(T‹pre›_‹map›*, int it, char*, size_t)`                 | Get the key of the entry given a position.                                                                                                                                                                                                                                                                                                                       | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`                        |
| `T‹pre›_‹eltype›* ‹pre›_‹map›_GetValue(T‹pre›_‹map›*, int it)`                       | Get the value of the entry given a position.                                                                                                                                                                                                                                                                                                                     | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_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`.                                                                                                                                                     | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_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.                                                                                                                                                                                                                                                                                                             | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`                        |
| `BOOL` `‹pre›_‹map›_Clear(T‹pre›_‹map›*)`                                            | Remove all entries from the map.                                                                                                                                                                                                                                                                                                                                 | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`                        |
| `BOOL` `‹pre›_‹map›_Remove(T‹pre›_‹map›*, int it)`                                   | Remove the entry at a position in the map.                                                                                                                                                                                                                                                                                                                       | `ePtx_Error_IllegalState`, `ePtx_Error_UnsupportedOperation`, `ePtx_Error_IllegalArgument`                        |

---

## PDF Toolbox SDK for .NET

The PDF Toolbox SDK for .NET lets you create PDF files using .NET.

:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::

:::tip
For the full API reference for the PDF Toolbox SDK, see the [.NET API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/dotnet/html/R_Project_API_Reference.htm).

:::

## IDisposable objects

Objects that must be closed explicitly (such as those based on `Document,` `ContentGenerator`, and `TextGenerator` classes) implement the `IDisposable` interface. Instead of calling `Dispose()` directly, it is recommended that you use the “using” statement:

```
using (Document document = ...)
{
 ...
}
// document.Dispose() is called implicitly here
```

See also [Garbage collection and closing objects](/overview/README.mdx#thread-safety).

## Error handling

Errors are reported using exceptions.
The following logic errors are mapped to the corresponding native exception classes:

- `IllegalArgument` maps to `System.ArgumentException`
- `IllegalState` maps to `System.InvalidOperationException`
- `UnsupportedOperation` maps to `System.NotSupportedException`

Additionally, the following infrastructure error is mapped:

- `IO` maps to `System.IO.IOException`

The remaining errors are modeled using exception classes that inherit from the class `PdfToolboxException`.

## Streams

The native stream interface `System.IO.Stream` is used.

## Lists

Lists implement the native list interface `System.Collections.Generic.IList`.

## Enumerables

Enumerables implement the native interface `System.Collection.Generic.IEnumerable`.

## Maps

Maps implement the native dictionary interface `System.Collections.Generic.IDictionary`.

---

## PDF Toolbox SDK for Java

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The PDF Toolbox SDK for Java lets you create PDF files using Java.

:::info
The PDF Toolbox SDK for Java requires **Java version 7 or higher**.
:::

:::note
For more information on the document model, graphics model, and thread safety, see [About the PDF Toolbox SDK](overview/README.mdx#document-model).
:::

:::tip
For the full API reference for the PDF Toolbox SDK, see the [Java API reference](https://api-reference.pdf-tools.com/toolsdk/4.3/javadoc/index.html?overview-summary.html).

:::

## Compilation

When using the Java interface, the Java archive `jar\com.pdf_tools.fourheights.pdftoolbox.jar` needs to be on the `CLASSPATH`. This can be done by either adding
it to the environment variable `CLASSPATH`, or by specifying it using the `-classpath` or `-cp` switch:

```
javac -cp ".;C:\Program Files\PDF Tools AG\jar\com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```

```
javac -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```

```
javac -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
sampleApplication.java
```

## Execution

Additionally, the library needs to be in one of the system’s library directories or added to the Java system property `java.library.path`.

In Windows, the library is defined by the environment variable `PATH`.

On Linux, the library is defined by `LD_LIBRARY_PATH`.

In macOS, the library is defined by `LD_LIBRARY_PATH`.

This can be achieved by either adding this system property dynamically at program startup before using the API, or by specifying it using the switch `-Djava.library.path` when starting the Java VM.

Choose the correct subdirectory (`win-x64` or `win-x86` on Windows) depending on the platform of the Java VM3. If the wrong data model is used, there is an error message similar to this: “Can't load IA 32-bit .dll on a AMD 64-bit platform”.

```
java -cp ".;C:\Program Files\PDF Tools AG\com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=C:\Program Files\PDF Tools AG\lib\win-x64" sampleApplication
```

In Linux, the path separator usually is a colon, so use:

```
java -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=/opt/pdftools.com/lib/linux-x64" sampleApplication
```

The path separator usually is a colon, so use:

```
java -cp ".:/path/to/com.pdf_tools.fourheights.pdftoolbox.jar" ^
"-Djava.library.path=/opt/pdftools.com/lib/osx-arm64" sampleApplication
```

## AutoCloseable objects

Objects that must be closed explicitly implement the `AutoCloseable` interface. Instead of calling `close()` directly, it is recommended that you use the “try ­with ­resources” statement:

```
try (Document document = ...) {
 ...
} // document.close() is called implicitly here
```

See also [Garbage collection and closing objects](/overview/README.mdx#thread-safety).

## Properties

Properties are modeled with setter and getter methods.

## Error handling

Errors are reported using exceptions.
The following logic errors are mapped to the corresponding native runtime exception classes and are not checked:

- `IllegalArgument` maps to `java.lang.IllegalArgumentException`
- `IllegalState` maps to `java.lang.IllegalStateException`
- `UnsupportedOperation` maps to `java.lang.UnsupportedOperationException`

Additionally, the following infrastructure error is mapped:

- `IO` maps to `java.io.IOException`
  The remaining errors are modeled using exception classes that inherit from a base class `PdfToolboxException`.

## Streams

The native stream interfaces cannot be used, because they are 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.pdf_tools.fourheights.pdftoolbox.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

Lists implement the native Java list interface `java.util.List`.

## Enumerables

Enumerables (lists that only allow iterating) implement the native Java iterator interface `java.util.Iterable`.

## Maps

Maps implement the native Java map interface `java.util.Map`.

---

## Use the PDF Toolbox SDK

import DocCardList from '@theme/DocCardList';

Learn about the most commonly used PDF Toolbox SDK features and find sample projects that help you integrate them.

:::tip
To see the full list of features for the PDF Toolbox SDK, see **[key features](overview/README.mdx#key-features)**.
:::

---

## Add and fill form fields

The PDF Toolbox SDK 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 PDF Toolbox SDK 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](../../code-samples/#add-form-field) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddFormFields/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddFormFields/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Fill form fields
You can learn how to fill form fields in a PDF document using out [Fill Form Fields](../../code-samples/#fill-form-fields) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FillFormFields/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FillFormFields/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FillFormFields/Download?technology=C).
:::

---

## Manage annotations

The PDF Toolbox SDK lets you manage annotations in PDF documents.
PDF annotations are elements that allow you to 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.

The PDF Toolbox SDK supports the following types of annotations:

| Type            | Annotation name        |
| --------------- | ---------------------- |
| Text Markup     | `Highlight``Popup``StickyNote``StrikeThrough``Underline` |
| Shape           | `Ellipse``Ink``Line``Polygon``PolyLine``Rectangle``Squiggly` |
| Navigation      | `InternalLink``WebLink` |
| Stamp           | `TextStamp``CustomStamp`          |
| File            | `FileAttachment`       |

## Manage annotations
Learn how to add annotations to a PDF using the [Add annotations](../../code-samples/#add-annotations-to-pdf) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddAnnotations/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddAnnotations/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our samples backlog.
:::

---

## Add and edit content

The PDF Toolbox SDK lets you add content to a PDF such as text, watermarks, barcodes and images.

## Content types
The PDF Toolbox SDK supports adding the following types of content:

- `Text`
- `Image`
- `Image Mask`
- `Path`

## Add content to a PDF
There is a wide range of use cases for these content types. See the following table for more details:

| Content type    | Use case example       |
| --------------- | ---------------------- |
| Text            | [Add text to a PDF](../../code-samples/#add-text-to-pdf)[Add a barcode to a PDF](../../code-samples/#add-barcode-to-pdf)[Add line numbers to a PDF](../../code-samples/#add-line-numbers-to-pdf)[Add a stamp to a PDF](../../code-samples/#add-stamp-to-pdf)[Add page numbers to a PDF](../../../pdf-toolbox-sdk/code-samples/#stamp-page-number-to-pdf) |
| Image           | [Add a QR code (Data Matrix) to a PDF](../../code-samples/#add-data-matrix-to-pdf)[Add an image to a PDF](../../code-samples/#add-image-to-pdf)  |
| Image Mask      | [Add an image mask to a PDF](../../code-samples/#add-image-mask-to-pdf) |
| Path            | [Add a vector graphic to a PDF](../../code-samples/#add-vector-graphic-to-pdf) |

:::note Quick start - Add text to a PDF
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddText/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddText/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddText/Download?technology=C).
:::

---

## Extract

The PDF Toolbox SDK lets you extract information such as text 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.

## Extract text
Learn how to extract text content from a PDF document using the [Extract all text from PDF](../../code-samples/#extract-all-text-from-pdf) sample project. This project also illustrates the use of heuristics to assemble text content into words and sentences based on their position on the page.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/TextExtraction/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/TextExtraction/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Extract images
Learn how to extract images from a PDF document using the [Extract all images and image masks from a PDF](../../code-samples#extract-all-images-and-image-masks-from-a-pdf) sample project. 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
:::

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ImageExtraction/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ImageExtraction/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ImageExtraction/Download?technology=C).
:::

## Extract signatures
Learn how to extract signature content from a PDF document using the [List Signatures in PDF](../../code-samples/#list-signatures-in-pdf) sample project. You can automatically extract signature information such as name, date, and contact information.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListSignatures/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListSignatures/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListSignatures/Download?technology=C).
:::

## Extract document attributes and metadata
You can learn how to extract document attributes and metadata from a PDF document using our [List document information of PDF](../../code-samples/#list-document-information-of-pdf) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=C).
:::

---

## Generate PDFs

The PDF Toolbox SDK lets you create a new PDF files from scratch using Java, .Net, and C. 
After creating the PDF document, use the PDF Toolbox SDK to [add content](./edit.mdx), [add form fields](./add-and-fill-form-fields.mdx), [manage metadata](./manage-metadata.mdx), and more.

## Create a new PDF document
Learn how to create a new PDF file using [Layout text on PDF page](../../code-samples#layout-text-on-pdf-page) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/LayoutText/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/LayoutText/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

---

## Manage metadata

The PDF Toolbox SDK 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.

## List document metadata
Learn how to list document attributes and metadata from a PDF document using the [List document information of PDF](../../code-samples/#list-document-information-of-pdf) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/ListInfo/Download?technology=C).
:::

## Add metadata
Learn how to set metadata such as the author, title, and creator of a PDF document using the [Add metadata to PDF](../../code-samples/#add-metadata-to-pdf) sample project. Optionally, copy metadata from another PDF document or the content of an XMP metadata file.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddMetadata/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddMetadata/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/AddMetadata/Download?technology=C).
:::

---

## Print

The PDF Toolbox SDK 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
You can learn how to flatten form fields in a PDF document using our [Flatten form fields](../../code-samples/#flatten-form-fields-in-pdf) sample project. This process turns the form field into non-interactive content while retaining its visual appearance.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FlattenFormFields/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FlattenFormFields/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FlattenFormFields/Download?technology=C).
:::

## Set page dimensions
Learn how to set the dimensions of a PDF page using the [Fit pages to specific page format](../../code-samples/#fit-pages-to-specific-page-format) sample project. 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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FitPage/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FitPage/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/FitPage/Download?technology=C).
:::

## Set page orientation
Learn how to adjust the orientation of a PDF page using the [Set page orientation](../../code-samples/#set-page-orientation) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RotatePages/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RotatePages/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RotatePages/Download?technology=C).
:::

## 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](../../code-samples/#place-multiple-pages-on-one-page) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/MultipleUp/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/MultipleUp/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/MultipleUp/Download?technology=C).
:::

---

## Redact

The PDF Toolbox SDK 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 pages or content like text, images, and paths.
You can also apply targeted redaction by removing or replacing individual characters (glyphs) from text fragments.

## Remove pages
Learn how to remove specific pages from a PDF document using the [Remove pages from PDF](../../code-samples/#remove-pages-from-pdf) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/Split/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/Split/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/Split/Download?technology=C).
:::

## Remove content
Learn how to iterate through the PDF to remove specific content using the [Remove White Text from PDF](../../code-samples/#remove-white-text-from-pdf) sample project. 

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RemoveWhiteText/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RemoveWhiteText/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Remove individual characters (glyphs)
Learn how to remove individual characters from fragments of text in a PDF document using the [Remove glyphs](../../code-samples/#remove-glyphs) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RemoveGlyphs/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_TOOLSDK/RemoveGlyphs/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our samples backlog.
:::

---

## Pdftools SDK

import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

Integrate a comprehensive development library with advanced PDF functionalities into in-house applications. The Pdftools SDK is a development library for .Net, C, C#, Java, and more, with a complete PDF feature set.

## Functionality

The following sections [Pdftools SDK](#pdftools-sdk) and [Toolbox add-on](#toolbox-add-on) provide an overview of the available features of the SDK.

### Pdftools SDK

Integrate a comprehensive development library with advanced PDF functionalities into in-house applications.

- [Archive PDFs to PDF/A](archive/README.mdx#archive-pdf-to-pdfa)
- [Compress and optimize PDFs](optimize/README.mdx)
- [Convert images to PDFs](convert/README.mdx#convert-images-to-pdf)
- [Convert PDFs to images](convert/README.mdx#convert-pdfs-to-images)
- [Embed e-invoice as ZUGFeRD or Factur-X](e-invoice/README.mdx)
- [Merge and split PDFs](assemble/README.mdx)
- [Sign and certify PDFs](sign-and-secure/sign/README.mdx)
- [Secure and encrypt PDFs](sign-and-secure/secure/README.mdx)
- [Validate PDFs](validate/README.mdx)

### Toolbox add-on

An add-on to the Pdftools SDK that provides low-level access to the content of PDF files.

- [Add and fill form fields](toolbox/add-and-fill-form-fields.mdx)
- [Edit](toolbox/edit.mdx)
- [Extract information](toolbox/extract.mdx)
- [Generate PDFs](toolbox/generate.mdx)
- [Layout for printing](toolbox/print.mdx)
- [Manage annotations](toolbox/annotate.mdx)
- [Manage metadata](toolbox/manage-metadata.mdx)
- [Redact](toolbox/redact.mdx)

:::info
Use both the Pdftools SDK and the Toolbox add-on with the Pdftools SDK Shell Tool.
:::

## Trial license

## Supported languages and frameworks

The Pdftools SDK and the Toolbox add-on are available for the following languages:

| Language or framework | Pdftools SDK documentation | Toolbox add-on documentation |
|-----------------------|----------------------------|------------------------------|
| C     | [C](./getting-started/pdftools-sdk/pdftools-sdk-c.mdx)       | [C](./getting-started/toolbox/toolbox-c.mdx) |
| Java  | [Java](./getting-started/pdftools-sdk/pdftools-sdk-java.mdx) | [Java](./getting-started/toolbox/toolbox-java.mdx)  |
| .NET  | [.NET](./getting-started/pdftools-sdk/pdftools-sdk-dotnet.mdx) | [.NET](./getting-started/toolbox/toolbox-dotnet.mdx) |
| Python| [Python](./getting-started/pdftools-sdk/pdftools-sdk-python.mdx) | [Python](./getting-started/toolbox/toolbox-python.mdx) |
| Other languages (Go) | [Get started with other programming languages](./getting-started/pdftools-sdk/pdftools-sdk-other-languages.mdx) | |

## Supported operating systems

The Pdftools SDK and the Toolbox add-on are 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 and the Toolbox add-on support 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 and the Toolbox add-on support 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](getting-started/README.mdx)**.
:::

---

## API references and technical notes

import DocCard from '@theme/DocCard';

The following sections provide links to the API refences for the Pdftools SDK and the Toolbox add-on.

## Pdftools SDK references

- [C API](https://api-reference.pdf-tools.com/pdfsdk/1.12/cdoc/files.html)
- [Java API](https://api-reference.pdf-tools.com/pdfsdk/1.12/javadoc/index.html)
- [.NET API](https://api-reference.pdf-tools.com/pdfsdk/1.12/dotnet/html/R_Project_API_Reference.htm)
- [Python API](https://api-reference.pdf-tools.com/pdfsdk/1.12/pydocs/index.html)

## Toolbox add-on references

- [C API](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/cdoc/files.html)
- [Java API](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/javadoc/index.html)
- [.NET API](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/dotnet/html/R_Project_API_Reference.htm)
- [Python API](https://api-reference.pdf-tools.com/pdfsdkxt/1.8/pydocs/index.html)

## Technical notes

Find an overview of the technical details about the Pdftools SDK and the Toolbox add-on for various programming languages on the [Technical notes](./technical-notes/README.mdx) overview page.

---

## Technical notes

import DocCardList from '@theme/DocCardList';

---

## C technical notes

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Learn about specifics and technical details about 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.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. In the PdfTools SDK, all the types used, 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, meaning that 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, a handle of the child type can be cast using a simple C-style cast:

```
(T‹prefix›_‹parentType›*)pChildTypeHandle
```

Upcasting is also possible using a C-style cast. Prior to casting, the child type of the handle can be determined 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 has occurred and the return value is legitimate.
2. If the return type of the function is not a Boolean or a pointer, call the `PdfTools_GetLastError` function. If this method returns `ePdfTools_Error_Success`, then no error has occurred.

More information about the error can be acquired from 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 is 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` is not 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 is 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 (Error handling is omitted):
```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 are modeled by means of 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 is 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 does not 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 (e.g. `PdfTools.Pdf.Document`, `PdfTools.Image.Document`, `PdfTools.Crypto.Providers.Provider`, or sub-classes) implement the `IDisposable` interface. Instead of calling `Dispose()` directly, it is recommended that you 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 & Iterables
The API uses different concepts for returning collections of elements depending on the context:
- lists (`System.Collections.Generic.IList`) are usually used when the elements are already in memory and random access is possible. Depending on the context manipulation (add, remove, etc.) might also be possible.
- iterables (`System.Collection.Generic.IEnumerable`) are usually used, when elements are retrieved on demand. They do not allow random access, but instead 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 to use 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 using multiple of our SDKs in the same project.
:::

---

## General technical notes

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This documentation explains how the Pdftools SDK interacts with your local operating system to [locate fonts](#locating-fonts), [locate color profiles](#locating-color-profiles), and to store [temporary files](#temporary-files-directory) and [cache files](#cache-directory).

## Locating fonts

Some Pdftools SDK features require fonts to be installed locally.

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

### Font directories

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

Font directories are traversed recursively in the order specified. If two fonts with the same name are found, the latter takes precedence, i.e. user fonts always take precedence over system fonts.

### Installing fonts in Windows

When a font is installed, it is installed by default only for a particular user.
It is important to either install fonts for all users or make sure the Pdf Tools
SDK is run under that user and the user profile is loaded.

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`.
   This includes user specific fonts from `C:\Users\\AppData\Local\Microsoft\Windows\Fonts` and app specific fonts from `C:\Program Files\WindowsApps`
3. `Fonts` directory, which must be a direct subdirectory of where `PdfToolsSdkAPI.dll` resides.

The directories are transversed recursively in this order.

### Installing fonts in Linux and Debian systems

In Linux, it is recommended that you install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font.

On Debian-based systems, the packages are `fontsliberation2`, `fontsnotocjk`, and `fonts opensymbol`.

Many PDF documents use Microsoft core fonts such as Arial, Times New Roman, and other fonts commonly used on Windows. Therefore, it is recommended that you install these fonts to your default font directories.
Many Linux distributions offer an installable package for Microsoft TrueType core fonts. For instance, on Debian-based systems, the package is `ttfmscorefontsinstalller`. Alternatively, you can download the fonts from http://corefonts.sourceforge.net/

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

1. `/usr/share/fonts`
2. `/usr/local/share/fonts`
3. `~/.fonts`
4. `$PDFFONTDIRor/usr/lib/X11/fonts/Type1`

The directories are transversed recursively in this order.

### Installing fonts in macOS

In macOS, it is recommended that you 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, it is recommended that you install these fonts to your default font directories.
Many Linux distributions offer an installable package for Microsoft TrueType core fonts. For instance, on Debian-based systems, the package is `ttfmscorefontsinstalller`. Alternatively, you can download the fonts from http://corefonts.sourceforge.net/

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

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

The directories are transversed recursively in this order.

### 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.

## Locating color profiles

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

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

1. `$PDF_ICC_PATH` if the environment variable is defined
2. the current working directory

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%\sys- tem32\spool\drivers\color\`.

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

- http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip
- http://www.color.org/srgbprofiles.html
- https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html

## Special Directories

Special directories are used by the Pdftools SDK 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 is not shared between different invocations and is deleted after the program is terminated.
The directory is determined as follows. The product checks for the existence of environment variables in the following order and uses the first path found:

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

1. The path specified by the `$PDFTMPDIR` environment variable.
2. The path specified by the `$TMP` environment variable.
3. The `/tmp` directory.

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 is persisted and shared between different invocations of a program. The actual caches are created in subdirectories. The content of this directory can safely be deleted to clean all caches.
This directory must be writable by the application. Otherwise, caches cannot be created or updated leading to significantly decreased performance.

If the user has a profile:

```
%LOCAL_APPDATA%\PDF Tools AG\Caches
```

If the user has no profile:

```
\PDF Tools AG\Caches
```

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).

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

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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 (e.g. `com.pdftools.pdf.Document`, `com.pdftools.image.Document`, `com.pdftools.crypto.providers.Provider`, or sub-classes) implement the `java.lang.AutoCloseable` interface. Instead of calling `close()` directly, it is recommended that you 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 cannot be used, because they are 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 & Iterables
The API uses different concepts for returning collections of elements depending on the context:
- lists (`java.util.List`) are usually used when the elements are already in memory and random access is possible. Depending on the context manipulation (add, remove, etc.) might also be possible.
- iterables (`java.util.Iterable`) are usually used, when elements are retrieved on demand. They do not allow random access, but instead 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 to use 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 using multiple of our SDKs in the same project.
:::

---

## 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](/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, e.g. by embedding 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](archive-pdf-pdfa.mdx)**.
:::

---

## 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](archive-image-pdfa-accessible.mdx)**.
:::

## Archive PDF to TIFF image archive

Convert PDFs to TIFF images in a format suitable for archiving using the [Archive conversion profile](../convert/conversion-profiles.mdx#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](archive-pdf-tiff.mdx)**.
:::

## 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](../convert/conversion-profiles.mdx) documentation.

---

## Archive an image to an accessible PDF

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfAccessibility/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

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](/docs/conversion-service/) can be used to recognize the characters in the documents (OCR) and tag the image with the recognized structure and text.

:::tip
For more background about converting images to PDF documents, see [Convert an image to a PDF document](../convert/convert-image-pdf.mdx).
:::

**Steps to archive a document**

1. [Reading the input image](#reading-the-input-image)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Specifying the conformance level](#specifying-the-conformance-level)
4. [Adding accessible content](#adding-accessible-content)
5. [Converting the image to a PDF document](#converting-the-image-to-a-pdf-document)
6. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
```

## Selecting 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.

```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
// Create the profile that defines the conversion parameters.
// The Archive profile converts images to PDF/A documents for archiving.
Archive profile = new Archive();
```

## Specifying 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 examples sets the document conformance to PDF/A-2a.

```csharp
// Set conformance of output document to PDF/A-2a
profile.Conformance = new Conformance(2, Conformance.PdfALevel.A);
```

```java
// Set conformance of output document to PDF/A-2a
profile.setConformance(new Conformance(new Conformance.PdfAVersion(2, Level.A)));
```

## Adding 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.

```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
// 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);
```

## Converting 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.

```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
// 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

```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
// 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=C).
:::

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)

:::tip
For more information about supported PDF/A standards, see [PDF/A overview](/docs/knowledge/pdf-a/).
:::

**Steps to archive a document**:

1. [Reading the input document](#reading-the-input-document)
2. [Creating a Conformance object](#creating-a-conformance-object)
3. [Creating a Validator object](#creating-a-validator-object)
4. [Running the Analyze method](#running-the-analyze-method)
5. [Creating a Converter object](#creating-a-converter-object)
6. [Running the Convert method](#running-the-convert-method)
7. [Checking the conversion results](#checking-the-conversion-results)
8. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```

## Creating 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`).

```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
// 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));
```

## Creating 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](../validate/validate-a-pdf.mdx).
However, during the PDF/A conversion process, additional information is also generated about the _potential_ conformance level of the document.

```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
// 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);
```

## Running 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`, i.e., 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.

```csharp
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
var analysisResult = validator.Analyze(inDoc, analysisOptions);
if (analysisResult.IsConversionRecommended) {
    return; // No conversion is required.
}
```

```java
// Run the analysis, and check the results.
// Only proceed if document is not conforming.
AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions);
if (analysisResult.getIsConversionRecommended())
{
    return; // No conversion is required.
}
```

## Creating 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.

```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
// 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);
```

## Running 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`.

```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
// 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);
```

## Checking 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:

```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
// 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

```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 document is not conforming.
var analysisResult = validator.Analyze(inDoc, analysisOptions);
if (analysisResult.IsConversionRecommended) {
    return; // No conversion is required.
}

// 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
// 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 document is not conforming.
    AnalysisResult analysisResult = validator.analyze(inDoc, analysisOptions);
    if (analysisResult.getIsConversionRecommended())
    {
        return; // No conversion is required.
    }

    // 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](../sign-and-secure/sign/sign-document.mdx)**.
:::

---

## Archive PDF document to TIFF image archive

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python).
:::

:::tip
For more information about PDF to image conversion profiles, see [Conversion profiles](../convert/conversion-profiles.mdx#pdf-to-image-conversion-profiles).
:::

**Steps to archive a document**

1. [Reading the input document](#reading-the-input-document)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the document to an image](#converting-the-document-to-an-image)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```

## Selecting 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.

```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
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
```

## Adjusting 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](../convert/conversion-profiles.mdx#pdf-to-image-conversion-profiles).

## Converting 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.

```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
// 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

```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
// 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](merge-pdfs.mdx)** 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](split-a-pdf.mdx)** 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Python).

Interested in other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process.

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](../convert/convert-image-pdf.mdx) and then merging the converted image into the output PDF document.

**Steps to merge PDF documents**:

1. [Creating a DocumentAssembler object](#creating-a-documentassembler-object)
2. [Reading the input documents](#reading-the-input-documents)
3. [Appending to the output document](#appending-to-the-output-document)
4. [Running the Assemble method](#running-the-assemble-method)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Creating 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.

```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
// 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)) {
```

## Reading the input documents

Iterate through the input document set, loading each file as a `Document`.

```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
// 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);
```

## Appending 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.

```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
// 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);
```

## Running 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 `DocumentAssember` object.

```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](../../api-references/technical-notes/dotnet-notes/#idisposable-objects).
:::

```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](../../api-references/technical-notes/java-notes/#autocloseable-objects).
:::

## Full example

```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
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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Split/Download?technology=Python).

Interested in a C or other language sample? [Let us know](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog1.
:::

Depending on the requirements, you can adjust the characteristics of the output document by setting the PageCopyOptions Class used in the assembly process.

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](../convert/convert-pdf-image.mdx).

**Steps to split PDF documents**:

1. [Opening the input Document](#opening-the-input-document)
2. [Creating the DocumentAssembler object](#creating-the-documentassembler-object)
3. [Appending to the output document](#appending-to-the-output-document)
4. [Running the Assemble method](#running-the-assemble-method)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Opening 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`.

```csharp
// Open input document
using var inStream = File.OpenRead(inPath);
using var inDoc = PdfTools.Pdf.Document.Open(inStream);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr)) {
```

## Creating 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.

```csharp
// Repeat for each page in the input document
for (int i = 1; i 

```java
// Repeat for each page in the input document
for (int i = 1; i 

## Appending 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.

```csharp
// Append the current page of the input PDF document to a single-page output document
docAssembler.Append(inDoc, i, i);
```

```java
// Append the current page of the input PDF document to a single-page output document
docAssembler.append(inDoc, i, i);
```

## Running 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 `DocumentAssember` object.

```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](../../api-references/technical-notes/dotnet-notes/#idisposable-objects).
:::

```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](../../api-references/technical-notes/java-notes/#autocloseable-objects).
:::

## Full example

```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 

```java
try (
    // Open input document
    FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
    Document inDoc = Document.open(inStr)) {
    for (int i = 1; i

---

## Code samples

import DocCardList from '@theme/DocCardList';
import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

Start using the Pdftools SDK and Toolbox add-on libraries with code samples. Integrate advanced PDF manipulation, optimization, and validation, as well as low-level access to the content of PDF files into your application in Java, .NET, C, and Python.

## Trial license

---

## Pdftools SDK code samples

Start using the Pdftools SDK library with code samples. Integrate advanced PDF manipulation, optimization, and validation tasks into your application in Java, .NET, C, and Python.

:::info
Select a code sample in a specific language and download it. The code samples illustrate how to integrate the SDK into your projects for specific use cases. Each code sample includes a README file that gives instructions on how to run the code sample to process one or multiple files.
:::

:::tip
Do you miss a specific sample and want us to include it here? Let us know through the [Contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## Toolbox add-on code samples

Start using the Toolbox add-on library with code samples. Integrate low-level access to the content of PDF files into your application in Java, .NET, and C.

:::info
Select a code sample in a specific language and download it. The code samples illustrate how to integrate the SDK into your projects for specific use cases. Each code sample includes a README file that gives instructions on how to run the code sample to process one or multiple files.
:::

:::tip
Do you miss a specific sample and want us to include it here? Let us know through the [Contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## 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](conversion-profiles.mdx#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](convert-pdf-image.mdx)**.
:::

---

## 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](conversion-profiles.mdx#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, PF/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](convert-image-pdf.mdx)**.
:::

---

---

## 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 coverting 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.
All colors and grayscale tones are converted to bitonal by applying dithering.
The output image is compressed using the CCITT Group 3 compression algorithm.

The following options may also be used:

- **Compression algorithm**: CCITT Group 3 or CCITT Group 4
- **Vertical resolution**: 98 DPI (Standard) or 196 DPI (High)

---

## Image to PDF conversion profiles

Image to PDF conversion profiles provide a set of default parameters that are used when coverting 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](/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](/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](/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](../archive/archive-image-pdfa-accessible.mdx)**.
:::

---

## Convert an image to a PDF document

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

**Steps to convert a document**

1. [Reading the input image](#reading-the-input-image)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the image to a PDF document](#converting-the-image-to-a-pdf-document)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.image.Document inDoc = com.pdftools.image.Document.open(inStr);
```

## Selecting a conversion profile

You start the image conversion process by creating a conversion `Profile` object to determine the [conversion profile](conversion-profiles.mdx).
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](conversion-profiles.mdx#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.

```csharp
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.

var profile = new Profiles.Default();
```

```java
// Create the profile that defines the conversion parameters.
// The Default profile converts images to PDF documents.

Default profile = new Default();
```

## Adjusting 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](conversion-profiles.mdx#image-to-pdf-conversion-profiles).

## Converting 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.

```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
// 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

```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
// 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python).
:::

:::tip
For more information about PDF to image conversion profiles, see [Conversion profiles](conversion-profiles.mdx#pdf-to-image-conversion-profiles).
:::

**Steps to convert a document**

1. [Reading the input document](#reading-the-input-document)
2. [Selecting a conversion profile](#selecting-a-conversion-profile)
3. [Adjusting the conversion profile](#adjusting-the-conversion-profile)
4. [Converting the document to an image](#converting-the-document-to-an-image)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```

## Selecting 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.

```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
// Create the profile that defines the conversion parameters.
// The Archive profile converts PDF documents to TIFF images for archiving.
Archive profile = new Archive();
```

## Adjusting 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](conversion-profiles.mdx#pdf-to-image-conversion-profiles).

## Converting 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.

```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
// 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

```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
// 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.

:::info 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/).
:::

## Full implementation example

For a complete example of embedding ZUGFeRD or Factur-X invoices using the PdfTools SDK, review [Create a ZUGFeRD invoice](../code-samples/pdftools-sdk-samples.mdx#create-a-zugferd-invoice) code sample.

## 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 the [Archive a PDF document to PDF/A](../archive/archive-pdf-pdfa.mdx).

## 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.

---

## Getting started with the Pdftools SDK

import DocCardList from '@theme/DocCardList';
import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

Get up and running with the Pdftools SDK, the Toolbox add-on, and the Pdftools SDK Shell Tool.

Find an integration guide in your language or framework by clicking one of the following cards:

## Functionality

The following sections [Pdftools SDK](#pdftools-sdk) and [Toolbox add-on](#toolbox-add-on) provide an overview of the available features of the SDK.

### Pdftools SDK

Integrate a comprehensive development library with advanced PDF functionalities into in-house applications.

- [Archive PDFs to PDF/A](archive/README.mdx#archive-pdf-to-pdfa)
- [Compress and optimize PDFs](optimize/README.mdx)
- [Convert images to PDFs](convert/README.mdx#convert-images-to-pdf)
- [Convert PDFs to images](convert/README.mdx#convert-pdfs-to-images)
- [Merge and split PDFs](assemble/README.mdx)
- [Sign and certify PDFs](sign-and-secure/sign/README.mdx)
- [Secure and encrypt PDFs](sign-and-secure/secure/README.mdx)
- [Validate PDFs](validate/README.mdx)

### Toolbox add-on

An add-on to the Pdftools SDK that provides low-level access to the content of PDF files.

- [Add and fill form fields](toolbox/add-and-fill-form-fields.mdx)
- [Edit](toolbox/edit.mdx)
- [Extract information](toolbox/extract.mdx)
- [Generate PDFs](toolbox/generate.mdx)
- [Layout for printing](toolbox/print.mdx)
- [Manage annotations](toolbox/annotate.mdx)
- [Manage metadata](toolbox/manage-metadata.mdx)
- [Redact](toolbox/redact.mdx)

:::info
Use both the Pdftools SDK and the Toolbox add-on with the Pdftools SDK Shell Tool.
:::

## Trial license

---

## Getting started with the Pdftools SDK

import DocCardList from '@theme/DocCardList';
import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

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 sample project, 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

---

## Get started with C

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, 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 for free.
:::

## Getting started with a sample project

Learn how to use the Pdftools SDK using a C sample project and convert a PDF file to an image.

### Prerequisites

This sample project uses **GCC toolset 4.8+** and **CMake version 3.16** or higher.

### Compile and run the sample

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C)**, and then unzip the file.
1. In the command line, navigate to the root directory of the unzipped sample project and then run:

    ```shell
    cmake .
    ```

1. Build the sample:

    ```shell
    cmake --build .
    ```

1. The sample project contains a PDF file `PdfPrimerWhitePaper.pdf`. To render it in multi-page TIFF image format, run:

    ```shell
    ./pdftoolspdf2imgsimple PdfPrimerWhitePaper.pdf PdfPrimerWhitePaper.tiff
    ```

The code sample 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:

```shell
./pdftoolspdf2imgsimple INPUT_FILE OUTPUT_FILE
```

:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
:::

## Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.

### 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:

    
    

    ```
    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.                                                                                                                 |

    

    

    ```
    /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 Linuxlinux-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. |

    

    

    ```
    /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:

    
    

    Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.

    

    

    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
    ```

    

    

    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
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::

:::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 additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::

To remove watermarks, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `PdfTools_Sdk_Initialize` function.

    ```c
    GOTO_CLEANUP_IF_FALSE_PRINT_ERROR(PdfTools_Sdk_Initialize(_T("insert-license-key-here"), NULL),
                                         _T("Failed to set the license key. %s (ErrorCode: 0x%08x).\n"), szErrorBuff,
                                         PdfTools_GetLastError());
    ```
    Replace the `insert-license-key-here` with the value of your license key. Include the less-than (``) signs.

To get a code sample with the `PdfTools_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a C code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C)** sample.
1. Unzip the file, and then find the `PdfTools_Sdk_Initialize` function in the main C file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C) sample includes `PdfTools_Sdk_Initialize` function in the `pdftoolspdf2imgsimple.c` file.
1. Uncomment the function and replace `insert-license-key-here` with your license key.

### Uninitialize the SDK

After processing files with the Pdftools SDK, call the `Uninitialize` function to unload the library correctly:

```c
// Uninitialize library
PdfTools_Uninitialize();
```

### Implement your use case

- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for C, consult the [C technical notes](../../api-references/technical-notes/c-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.

---

## Get started with .NET

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, and then explains how to integrate the Pdftools SDK into your application with .NET.

:::tip
Try the Pdftools SDK without a license key for free.
:::

## Prerequisites

The Pdftools SDK for .NET requires **.NET and .NET Core 2.0 or higher**, or **.NET Framework 4.6.1 or higher**.

## Getting started with a sample project

Learn how to use the Pdftools SDK using a C# sample project and convert a PDF file to an image.

### Compile and run the sample

Switch between the following tabs to display steps for the command line interface or for the Visual Studio. To compile and run the sample, follow these steps:

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, and then unzip the file.
1. In the command line, navigate to the root directory of the unzipped sample project.
1. To render the sample PDF file `PdfPrimerWhitePaper.pdf` to a multi-page TIFF image format, run the following command:

    ```shell
    dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj PdfPrimerWhitepaper.pdf tiff_output.tiff
    ```

The code sample 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:
```shell
dotnet run --framework net6.0 --project PdfToolsPdf2ImgSimple.csproj INPUT_FILE OUTPUT_FILE
```

:::info
This documentation uses Visual Studio 2022.
:::

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)**, and then unzip the file.
1. In the sample folder, double click `PdfToolsPdf2ImgSimple.csproj`
1. Click **Build** -> **Build Solution** to compile the project.
1. Within the sample project, open your terminal.
1. The sample project 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 sample 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:

```shell
./bin/Debug/net6.0/PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```

:::tip
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
:::

## Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.

### Add the SDK to your project

In the project directory, run the following command:

```shell
dotnet add package PdfTools
```

Optional: If you want to use a specific version of the Pdftools SDK, run the following command:

```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.

:::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
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::

:::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 additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::

To remove watermarks, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.

    ```csharp
    Sdk.Initialize("insert-license-key-here");
    ```
    Replace the `insert-license-key-here` with the value of your license key. Include the less-than (``) signs.

:::info Try it without license key
You can try the Pdftools SDK without a license with watermarked results. For more information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/). Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::

To get a working code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a C# code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the C# file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS) includes the `SDK.initialize` method in the `Program.cs` file.
1. Uncomment the method and replace the `insert-license-key-here` with your license key.

### Implement your use case

- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for .NET, consult the [.NET technical notes](../../api-references/technical-notes/dotnet-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.

---

## Get started with Java

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, 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 for free.
:::

## Prerequisites

The Pdftools SDK for Java requires **Java version 8 or higher**.

## Getting started with a sample project

Learn how to use the Pdftools SDK using a Java sample project and convert a PDF file to an image.

### Compile and run the sample

Switch between the following tabs to display steps for the command line interface or for the Eclipse IDE. To compile and run the sample, follow these steps:

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, and then unzip the file.
1. In the command line, navigate to the root directory of the unzipped sample project, and then compile the Java source file:

    
    

    ```bash
    javac -cp jar/com.pdftools.jar:. PdfToolsPdf2ImgSimple.java
    ```

    
    

    ```bash
    javac -cp jar/com.pdftools.jar;. PdfToolsPdf2ImgSimple.java
    ```

    
    

1. Run the sample:

    
    

    ```bash
    java -cp jar/com.pdftools.jar:bin:. PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff
    ```

    
    

    ```bash
    java -cp jar/com.pdftools.jar;bin;. PdfToolsPdf2ImgSimple PdfPrimerWhitepaper.pdf tiff_output.tiff
    ```

    
    

The code sample 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
java -cp jar/com.pdftools.jar:bin:. PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```

```bash
java -cp jar/com.pdftools.jar;bin;. PdfToolsPdf2ImgSimple INPUT_FILE OUTPUT_FILE
```

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)**, and then unzip the file.
1. From the unzipped file, import the `.project` file into the Eclipse IDE. The source file `PdfToolsPdf2ImgSimple.java` is compiled automatically.
1. Right-click the `java` file, and then select **PdfToolsPdf2ImgSimple.java** > **Run As** > **Run configurations...**.
1. Create a new configuration for a **Java Application**, and then add the required arguments, for example: 

    ```
    PdfPrimerWhitepaper.pdf OutputPdfPrimerWhitePaper.tiff
    ```

:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
:::

## Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.

### Add the SDK to your project

The Pdftools SDK for Java is available on Maven. To add the Pdftools SDK for Java to your project, select your operating system and system architecture and add the following to your `pom.xml`:

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    linux-x64
    so

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    linux-x64-glibc2.12
    so

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    linux-arm64
    so

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    osx-arm64
    dylib

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    osx-x64
    dylib

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    win-x64
    dll

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    win-x86
    dll

```

```xml

    com.pdftools
    pdftools-sdk
    1.12.0

    com.pdftools
    pdftools-sdk
    1.12.0
    win-arm64
    dll

```

1. Download the [Pdftools SDK for Java](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_Java-latest.zip) product kit, and then unzip the file.
2. Add the `jar` file to your project's classpath.
3. Copy the `lib` folder containing the native binary files to your project, for example `/lib`.

### Load the SDK

The Pdftools SDK for Java requires you to load the underlying native binary files suitable for your operating system and system architecture at runtime.

There are two ways how to load the Pdftools SDK for Java with Maven:

1. If you are consuming Java libraries directly from the local Maven repository, load the native binary files using the following code:

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-linux-x64.so");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-linux-x64-glibc2.12.so");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-linux-arm64.so");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-osx-arm64.dylib");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-osx-x64.dylib");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-win-x64.dll");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-win-x86.dll");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/pdftools-sdk/1.12.0/pdftools-sdk-1.12.0-win-arm64.dll");
    ```

    
    

1. Alternatively, use the system library path:

    1. Add the Pdftools SDK `lib` directory to the system library path.
        - Windows: Environment variable `PATH`
        - Linux and macOS: Defined by `LD_LIBRARY_PATH`
        - Or specify the path using the VM arg `-Djava.library.path=`.

    1. Load the library using:

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-linux-x64");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-linux-x64-glibc2.12");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-linux-arm64");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-osx-arm64");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-osx-x64");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-win-x64");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-win-x86");
        ```

        
        

        ```java
        System.loadLibrary("pdftools-sdk-1.12.0-win-arm64");
        ```

        
        

In the default configuration of the Pdftools SDK, the `lib` directory has the following structure:

```
lib
├── linux-x64
├── linux-arm64
├── osx-arm64
├── osx-x64
├── win-x64
└── win-x86
└── win-arm64
```

If you are using the default directory structure, load the library from the respective subfolder in `lib` directory appropriate for your operating system and system architecture.

There are two ways to load the Pdftools SDK for Java manually:

1. Load the Pdftools SDK using the system library path:

    1. Add the directory for your operating system to the system library path.
        - Windows: environment variable `PATH`.
        - Linux and macOS: defined by `LD_LIBRARY_PATH`.
        - Specify the path using the Java VM argument `-Djava.library.path=`.

    1. Load the library from the system's library path by using:

        ```java
        System.loadLibrary("PdfToolsSdk");
        ```

1. Alternatively, load the Pdftools SDK by specifying the absolute path:

    
    

    ```java
    System.load(new File("lib/linux-x64/libPdfToolsSdk.so").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/linux-x64/libPdfToolsSdk.so").getAbsolutePath());
    ```

    :::note
    Ensure to download a proper package. Native libraries suitable for glibc2.12+ are provided as a [separate download](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/PdfToolsSDK_glibc2.12-latest.zip).
    :::

    
    

    ```java
    System.load(new File("lib/linux-arm64/libPdfToolsSdk.so").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/osx-arm64/libPdfToolsSdk.dylib").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/osx-x64/libPdfToolsSdk.dylib").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-x64/PdfToolsSdk.dll").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-x86/PdfToolsSdk.dll").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-arm64/PdfToolsSdk.dll").getAbsolutePath());
    ```

    
    

:::note
Note the difference between:
* `System.load(..)`: Loads the library from an absolute file path.
* `System.loadLibrary(..)`: Load the library from the system's library path.
:::

:::info
If you are shipping your application, ensure to ship it with the native binary files. 
Note that you must load the native binary files from the file system and cannot load them from within a `jar` file or other bundle.
:::

### Optional: Initialize the SDK

Learn how to remove watermarked output of the Pdftools SDK using a valid license key.

:::tip
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::

:::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 additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::

To remove watermarks, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.

    ```java
    Sdk.initialize("insert-license-key-here");
    ```
    Replace the `insert-license-key-here` with the value of your license key. Include the less-than (``) signs.

To get a working code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a Java code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the main Java file of the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java) sample includes `SDK.initialize` method in the `PdfToolsPdf2ImgSimple.java` file.
1. Uncomment the method and replace `insert-license-key-here` with your license key.

### Implement your use case

- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- For more technical information about the Pdftools SDK for Java, consult the [Java technical notes](../../api-references/technical-notes/java-notes.mdx).
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.

---

## Get started with other programming languages

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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 the following 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 below.
:::

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 the following code inside it:
    

    

    ```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+")
      var pInStream *C.FILE
      var pOutStream *C.FILE
      var pInDoc *C.TPdfToolsPdf_Document
      var pOutDoc *C.TPdfToolsImage_Document
      var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
      var pConverter *C.TPdfToolsPdf2Image_Converter

      // 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()
    }
    ```

    
    

    ```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+")
      var pInStream *C.FILE
      var pOutStream *C.FILE
      var pInDoc *C.TPdfToolsPdf_Document
      var pOutDoc *C.TPdfToolsImage_Document
      var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
      var pConverter *C.TPdfToolsPdf2Image_Converter

      // 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()
    }
    ```

    

    

    ```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+")
      var pInStream *C.FILE
      var pOutStream *C.FILE
      var pInDoc *C.TPdfToolsPdf_Document
      var pOutDoc *C.TPdfToolsImage_Document
      var pProfile *C.TPdfToolsPdf2ImageProfiles_Profile
      var pConverter *C.TPdfToolsPdf2Image_Converter

      // 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 are watermarked. Get in touch with 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 sample project with Python.

:::tip
Try the Pdftools SDK without a license key for free.
:::

:::info
The Python interface is implemented as a wrapper around the Pdftools SDK's [C API](https://api-reference.pdf-tools.com/pdfsdk/latest/cdoc/files.html).
:::

## Prerequisites

The Pdftools SDK for Python requires **Python 3.6 or higher**.

## Getting started with a sample project

Learn how to use the Pdftools SDK using a Python sample project and convert a PDF file to an image.

### Download and run the sample

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)**, and then unzip the file.
1. Install the Pdftools SDK package by running the following command:

    ```bash
    pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/pdftools_sdk-latest.tar.gz
    ```

1. In the command line, navigate to the root directory of the unzipped sample project, where you can find the `pdf2_img_simple.py` file.
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 sample 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
python ./pdf2_img_simple.py INPUT_PDF IMAGE_OUTPUT_PATH
```

## Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.

### Add the SDK to your project

1. Install the Python package:

    ```shell
    pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDK/latest/pdftools_sdk-latest.tar.gz
    ```

1. From the [Pdftools SDK code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download any Python code sample.
1. Unzip a code sample and review the `README.md` file with usage details. Every code sample includes a `README.md` with different usage instructions.
1. Import the following 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](../../code-samples/pdftools-sdk-samples.mdx#convert-pdf-to-image) sample. Every sample includes a single Python file from which you can copy the imports. In case you want to use another functionality, copy the correct imports into your project with the following steps:

1. Open the [Pdftools SDK code samples](../../code-samples/pdftools-sdk-samples.mdx).
1. Download a sample. For example: [Decrypt an encrypted PDF](../../code-samples/pdftools-sdk-samples.mdx#decrypt-an-encrypted-pdf)
1. Unzip the downloaded sample.
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
You can try the Pdftools SDK without a license key for free. This section is **optional** if you want to evaluate this SDK. Initialization only lets you remove watermarks added to output files.
:::

:::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 additional information, review [Pdftools SDK license management](/docs/licenses/products/pdf-tools-sdk-license/).
:::

To remove watermarks, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Pdftools SDK, first call the `Sdk.initialize` method.

    ```python
    Sdk.initialize("insert-license-key-here")
    ```
    Replace the `insert-license-key-here` with the value of your license key. Include the less-than (``) signs.

To get a code sample with the `PdfTools_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page, download and unzip a Python code sample. For example: Download **[Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in a Python file included with the sample. For example: [Convert PDF to image](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python) sample includes `SDK.initialize` method in the `pdf2_img_simple.py` file.
1. Uncomment the method and replace `insert-license-key-here` with your license key.

### Implement your use case

- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-samples.mdx) page.
- If you need to configure a proxy, review [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) documentation section.

---

## Pdftools SDK Shell Tool

Learn how to use the Pdftools SDK and the Toolbox add-on 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

:::note
As of this version, the Pdftools SDK Shell Tool supports the following features of the Pdftools SDK.
Support for additional features will be added soon.
:::

| Feature                      | Description                                                                    | Support as of version    |
| ---------------------------- | ------------------------------------------------------------------------------ | ------------------------ |
| Image to PDF                 | Convert images to single PDF or PDF/A                                          | 1.0.0 +                  |
| PDF to PDF/A                 | Validate PDF conformance; Convert documents to PDF/A                           | 1.2.0 +                  |
| Compression and optimization | Compress and optimize PDF documents for web, archiving, printing or file size  | 1.0.0 +                  |
| Security                     | Sign, certify PDF documents; Validate signatures in PDF documents              | 1.4.0+                   |
| Rendering                    | Render PDF documents to images for fax, archive, or viewing                    | 1.1.0+                   |
| Merging and splitting        | Merge and split PDF documents to assemble new output documents                 | 1.1.0+                   |

## Usage

The general usage is

```bash
> pdf [sdk_options]  [input_options]  [: ] [ [output_options]]
```

### Chaining 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
```

---

## Getting started with the Toolbox add-on

import DocCardList from '@theme/DocCardList';
import PdftoolsSdkLicenseTable from '/src/modules/reference/ref_pdftools-sdk-license-use.mdx';

Welcome to the Toolbox add-on getting started guides. The Toolbox add-on is a library that provides functionality for developers who need low-level access to the content of PDF files. Guides for C, .NET, and Java explain how to work with a sample project, and then walk you through the steps necessary to integrate the SDK into your application.

## Trial license

---

## Get started with C

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with the C programming language.

## 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. Reach out to 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](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).

## Getting started with a sample project

Learn how to use the Toolbox add-on using a C sample project and extract all images and image masks from a PDF document.

### Prerequisites

This sample project uses **GCC toolset 4.8+** and **CMake version 3.16** or higher.

### Compile and run the sample

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the `toolboximageextraction.c` file, replace the string `"insert-license-key-here"` 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 as you copied it. Include the less-than (``) signs.

1. In the command line, navigate to the root directory of the unzipped sample project, and then run the following command:

    ```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 sample 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:

```shell
./toolboximageextraction INPUT_FILE OUTPUT_FILE
```

:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) 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:

    
    

    ```
    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.                                                                                                                 |

    

    

    ```
    /opt/pdftools.com/
    ```

    Included subdirectories are:

    | Subdirectory | Description                                                                                                              |
    | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
    | `lib`          |  Runtime executable binaries for all supported platforms: linux-x64/libPdfToolsSdk.so for 64-bit Linuxlinux-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. |

    

    

    ```
    /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:

    
    

    Add the `lib\win-x64`, `lib\win-arm64` or `lib\win-x86` subdirectory to the `%PATH%` environment variable.

    

    

    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/libPdfTools_Toolbox.so /usr/lib
    ```

    

    

    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 SDK

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).

:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::

To initialize the Toolbox add-on with your license key, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Ptx_Sdk_Initialize` function:

    ```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());
    ```
    Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (``) signs.

To get a code sample with the `Ptx_Sdk_Initialize` function that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a C code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C)** sample.
1. Unzip the file, and then find the `Ptx_Sdk_Initialize` function in the C file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C) includes the `Ptx_Sdk_Initialize` method in the `toolboximageextraction.c` file.
1. Replace the `insert-license-key-here` with your license key.

### Uninitialize the SDK

After processing files with the Toolbox add-on, call the `Uninitialize` function to unload the library correctly:

```c
// Uninitialize library
Ptx_Uninitialize();
```

### Implement your use case

- Find more use cases and sample projects on the Toolbox add-on [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Toolbox add-on for C, consult the [C technical notes](../../api-references/technical-notes/c-notes.mdx).

---

## Get started with .NET

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with .NET.

## 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. Reach out to 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](/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**.

## Getting started with a sample project

Learn how to use Toolbox add-on using a C# sample project and extract all images and image masks from a PDF document.

### Compile and run the sample

Switch between the following tabs to display steps for the command line interface or for the Visual Studio. To compile and run the sample, follow these steps:

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the `Program.cs` file, replace the string `"insert-license-key-here"` with your license key:

    ```csharp
    Sdk.Initialize("insert-license-key-here", null);
    ```
    Use the license key in the same format as you copied it. Include the less-than (``) signs.

1. In the command line, navigate to the root directory of the unzipped sample 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
    dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj ImageCollection.pdf /tmp/images
    ```

The code sample 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:

```shell
dotnet run --framework net6.0 --project ToolboxImageExtraction.csproj INPUT_FILE OUTPUT_DIRECTORY
```

:::info
This documentation uses Visual Studio 2022.
:::

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)**, and then unzip the file.
1. In the sample folder, double click `ToolboxImageExtraction.csproj`
1. In the `Program.cs` file, replace the string `"insert-license-key-here"` with your license key:

  ```csharp
  Sdk.Initialize("insert-license-key-here", null);
  ```

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 sample 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:

```shell
ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```

:::tip
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) 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

In the project directory, run the following command:

```shell
dotnet add package PdfTools.Toolbox
```

Optional: If you want to use a specific version of the Pdftools SDK, run the following command:

```shell
dotnet add package PdfTools.Toolbox --version 
```

:::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 SDK

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).

:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::

To initialize the Toolbox add-on with your license key, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.

    ```csharp
    Sdk.Initialize("insert-license-key-here", null);
    ```
    Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (``) signs.

To get a code sample with the `Sdk.Initialize` method that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a C# code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the C# file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS) includes the `SDK.initialize` method in the `Program.cs` file.
1. Replace the `insert-license-key-here` with your license key.

### Implement your use case

- Find more use cases and sample projects on the Toolbox add-on [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Toolbox add-on for .NET, consult the [.NET technical notes](../../api-references/technical-notes/dotnet-notes.mdx).

---

## Get started with Java

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide walks you through the steps to use a sample project, and then explains how to integrate the Toolbox add-on into your application with the Java programming language.

## 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. Reach out to 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](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).

## Prerequisites

The Toolbox add-on for Java requires **Java version 8 or higher**.

## Getting started with a sample project

Learn how to use Toolbox add-on using a Java sample project and extract all images and image masks from a PDF document.

### Compile and run the sample

To compile and run the sample, follow these steps:

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the `ToolboxImageExtraction.java` file, replace the string `"insert-license-key-here"` with your license key:

    ```Java
    Sdk.initialize("insert-license-key-here", null);
    ```
    Use the license key in the same format as you copied it. Include the less-than (``) signs.

1. In the command line, navigate to the root directory of the unzipped sample project.
1. Create an output directory:

    ```
    mkdir output_images
    ```

1. Compile the Java source file:

    
    

    ```bash
    javac -cp jar/com.pdftools.toolbox.jar:. ToolboxImageExtraction.java
    ```

    
    

    ```bash
    javac -cp jar/com.pdftools.toolbox.jar;. ToolboxImageExtraction.java
    ```

    
    

1. To extract all images and image masks from the sample PDF file `ImageCollection.pdf` to the output directory `/output_images`, run the following command:

    
    

    ```bash
    java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction ImageCollection.pdf /output_images
    ```

    
    

    ```bash
    java -cp jar/com.pdftools.toolbox.jar;bin;. ToolboxImageExtraction ImageCollection.pdf /output_images
    ```

    
    

The code sample 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
java -cp jar/com.pdftools.toolbox.jar:bin:. ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```

```bash
java -cp jar/com.pdftools.toolbox.jar;bin;. ToolboxImageExtraction INPUT_FILE OUTPUT_DIRECTORY
```

:::note
You can apply a similar procedure described in this tutorial for other code samples. For more information, see [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
:::

## Integrate the SDK into your application

Integrate and initialize the Pdftools SDK into your application by following the instructions in the following sections.

### Add the SDK to your project

The Toolbox add-on for Java is available on Maven. To add the Toolbox add-on for Java to your project, select your operating system and system architecture and add the following to your `pom.xml`:

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    linux-x64
    so

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    linux-arm64
    so

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    osx-arm64
    dylib

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    osx-x64
    dylib

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    win-x64
    dll

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    win-x86
    dll

```

```xml

    com.pdftools
    toolbox
    1.8.0

    com.pdftools
    toolbox
    1.8.0
    win-arm64
    dll

```

1. Download the [Toolbox add-on for Java](https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/PdfTools_Toolbox_Java-latest.zip) product kit, and then unzip the file.
2. Add the `jar` file to your project's classpath.
3. Copy the `lib` folder containing the native binary files to your project, for example `/lib`.

### Load the Toolbox add-on

The Toolbox add-on for Java requires you to load the underlying native binary files suitable for your operating system and system architecture at runtime.

There are two ways how to load the Toolbox add-on for Java with Maven:

1. If you are consuming Java libraries directly from the local Maven repository, load the native binary files using the following code:

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-linux-x64.so");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-linux-arm64.so");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-osx-arm64.dylib");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-osx-x64.dylib");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-win-x64.dll");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-win-x86.dll");
    ```

    
    

    ```java
    System.load(System.getProperty("user.home") + "/.m2/repository/com/pdftools/toolbox/1.8.0/toolbox-1.8.0-win-arm64.dll");
    ```

    
    

1. Alternatively, use the system library path:

    1. Add the Toolbox add-on `lib` directory to the system library path.
        - Windows: Environment variable `PATH`
        - Linux and macOS: Defined by `LD_LIBRARY_PATH`
        - Or specify the path using the VM arg `-Djava.library.path=`.

    1. Load the library using:

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-linux-x64");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-linux-arm64");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-osx-arm64");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-osx-x64");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-win-x64");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-win-x86");
        ```

        
        

        ```java
        System.loadLibrary("toolbox-1.8.0-win-arm64");
        ```

        
        

In the default configuration of the Toolbox add-on, the `lib` directory has the following structure:

```
lib
├── linux-x64
├── linux-arm64
├── osx-arm64
├── osx-x64
├── win-x64
└── win-x86
└── win-arm64
```

If you are using the default directory structure, load the library from the respective subfolder in `lib` directory appropriate for your operating system and system architecture.

There are two ways to load the Toolbox add-on for Java manually:

1. Load the Toolbox add-on using the system library path:

    1. Add the directory for your operating system to the system library path.
        - Windows: environment variable `PATH`.
        - Linux and macOS: defined by `LD_LIBRARY_PATH`.
        - Specify the path using the Java VM argument `-Djava.library.path=`.

    1. Load the library from the system's library path by using:

        ```java
        System.loadLibrary("PdfTools_Toolbox");
        ```

1. Alternatively, load the Toolbox add-on by specifying the absolute path:

    
    

    ```java
    System.load(new File("lib/linux-x64/libPdfTools_Toolbox.so").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/linux-arm64/libPdfTools_Toolbox.so").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/osx-arm64/libPdfTools_Toolbox.dylib").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/osx-x64/libPdfTools_Toolbox.dylib").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-x64/PdfTools_Toolbox.dll").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-x86/PdfTools_Toolbox.dll").getAbsolutePath());
    ```

    
    

    ```java
    System.load(new File("lib/win-arm64/PdfTools_Toolbox.dll").getAbsolutePath());
    ```

    
    

:::note
Note the difference between:
* `System.load(..)`: Loads the library from an absolute file path.
* `System.loadLibrary(..)`: Load the library from the system's library path.
:::

:::info
If you are shipping your application, ensure to ship it with the native binary files. 
Note that you must load the native binary files from the file system and cannot load them from within a `jar` file or other bundle.
:::

### Initialize the SDK

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK).

:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::

To initialize the Toolbox add-on with your license key, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.

    ```java
    Sdk.initialize("insert-license-key-here", null);
    ```
    Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (``) signs.

To get a code sample with the `Sdk.initialize` method that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a Java code sample. For example: Download **[Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the main Java file of the sample. For example: [Extract all images and image masks from a PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java) sample includes `SDK.initialize` method in the `ToolboxImageExtraction.java` file.
1. Replace `insert-license-key-here` with your license key.

### Implement your use case

- Find more use cases and sample projects on the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.
- For more technical information about the Pdftools SDK for Java, consult the [Java technical notes](../../api-references/technical-notes/java-notes.mdx).

---

## Get started with Python

This guide walks you through the steps to use the Toolbox add-on in a sample project with Python.

:::info
The Python interface is implemented as a wrapper around the Toolbox add-on C API. For more details about specific functions and properties, review the [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. Reach out to 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](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).

## Prerequisites

The Toolbox add-on for Python requires **Python 3.6 or higher**.

## Getting started with a sample project

Learn how to use the Toolbox add-on using a Python sample project and add text to a PDF.

### Download and run the sample

1. Download a **[sample project](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python)**, and then unzip the file.
1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. In the code sample folder, open the Python file (for example `add_text.py`).
1. In the `add_text.py` file, replace the string `"insert-license-key-here"` with your license key:

    ```python
    # Set and check license key. If the license key is not valid, an exception is thrown.
    Sdk.initialize("insert-license-key-here", None)
    ```
    Use the license key in the same format as you copied it. Include the less-than (``) signs.

1. Install the package for the Toolbox add-on by executing:

    ```bash
    pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/pdftools_toolbox-latest.tar.gz
    ```

1. In the command line, navigate to the root directory of the unzipped sample project, where `add_text.py` resides.
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 sample 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 the following 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 https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/pdftools_toolbox-latest.tar.gz
    ```

1. From the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download any Python code sample.
1. Unzip a code sample and review the `README.md` file with usage details. Every code sample includes a `README.md` with different usage instructions.
1. Import the following 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](../../code-samples/pdftools-sdk-toolbox-samples.mdx#add-text-to-pdf) sample. Every sample includes a single Python file from which you can copy the imports. In case you want to use another functionality, copy the correct imports into your project with the following steps:

1. Open the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx).
1. Download a sample. For example: [Place multiple pages on one page](../../code-samples/pdftools-sdk-toolbox-samples.mdx#place-multiple-pages-on-one-page)
1. Unzip the downloaded sample.
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).

:::tip Getting a license key
Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the [Contact page](https://www.pdf-tools.com/contact/) to get a full license.
:::

To initialize the Toolbox add-on with your license key, follow these steps:

1. Locate your license key. For more information, review [Find the license key](/docs/licenses/products/pdf-tools-sdk-license/#find-the-license-key).
1. Before you call any function of the Toolbox add-on, first call the `Sdk.initialize` method.

    ```python
    Sdk.initialize("insert-license-key-here", None)
    ```
    Replace `insert-license-key-here` with the value of your license key. Use the license key in the same format as you copied it. Include the less-than (``) signs.

To get a code sample with the `Sdk.Initialize` method that you can use as a reference for your code, follow these steps:

1. On the [Code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page, download and unzip a Python code sample. For example: Download **[Add text to PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python)** sample.
1. Unzip the file, and then find the `Sdk.initialize` method in the Python file of the sample. For example: [Add text to PDF](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Python) includes the `SDK.initialize` method in the `add_text.py` file.
1. Replace the `insert-license-key-here` with your license key.

### Implement your use case

Download other sample projects that show you how to implement specific use cases with the Toolbox add-on using Python. Review the [Toolbox add-on code samples](../../code-samples/pdftools-sdk-toolbox-samples.mdx) page.

---

## 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](./optimization-profiles.mdx) 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 (i.e. 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 unecessary data:
  - Redundant objects
  - Embedded standard fonts (e.g. Courier, Arial, 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](optimize-a-pdf.mdx)** 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 subseting 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, document structure information, etc.
- 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, i.e. 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, e.g. with a lossless compression type 
- Collapsing redundant objects 
- Removing unused resources
- Removing irrelevant information for printing such as thumbnails, article threads, document structure information, etc.

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, piece-info dictionaries, etc.
- 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Python).
:::

The Pdftools SDK currently supports five [optimization profiles](optimization-profiles.mdx) 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 (e.g., 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. [Reading the input document](#reading-the-input-document)
2. [Creating an Optimizer object](#creating-an-optimizer-object)
3. [Setting an optimization profile](#setting-an-optimization-profile)
4. [Running the OptimizeDocument method](#running-the-optimizedocument-method)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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 `Converter`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```

## Creating 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.

```csharp
// Create the Optimizer object.

Optimizer optimizer = new Optimizer();
```

```java
// Create the Optimizer object.

Optimizer optimizer = new Optimizer();
```

## Setting an optimization profile

The `Profile` object controls the behavior of the `Optimizer` object during the optimization process.
The [profile](optimization-profiles.mdx) 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.

```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
// 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
```

## Running the OptimizeDocument method

After creating the `Optimize` 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.

```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
// 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](../sign-and-secure/secure/pdf-encryption.mdx).
:::

## Full example

```csharp
// Open the PDF document to validate
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
// 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))
{
}
```

---

## Release notes

Learn about the latest updates of:

- [Pdftools SDK](#pdftools-sdk)
- [Toolbox add-on](#toolbox-add-on)
- [Pdftools SDK Shell Tool](#pdftools-sdk-shell-tool)

## Pdftools SDK

### Version 1.12.0

19 June 2025

#### Added

- 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

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

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 samples now include links to Jupyter notebooks marked as the **Open in colab** buttons. Review the following code samples:
    - [Pdftools SDK code samples](./code-samples/pdftools-sdk-samples.mdx)
    - [Toolbox add-on code samples](./code-samples/pdftools-sdk-toolbox-samples.mdx)

### 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

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

20 January 2025

#### Added

- 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 the [Python getting started guide](./getting-started/pdftools-sdk/pdftools-sdk-python.mdx).

#### 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

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

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](./api-references/technical-notes/general-notes.mdx#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

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](optimize/optimize-a-pdf.mdx) 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

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

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](sign-and-secure/sign/sign-document.mdx). 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

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

31 May 2023

#### Added

- Signature validation for the [digital signing](sign-and-secure/sign/README.mdx) 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 (see [Getting-started](README.mdx)).
- **Updated Java API ZIP archive layout**: The Java API ZIP archive directory layout has been updated (see [Getting-started](README.mdx)).

## Toolbox add-on

### Version 1.8

19 June 2025

#### Added

- The Toolbox add-on now natively supports Linux ARM64 processor architecture.
- `GetResolution` method was added to the `Image` class. Review the following API references for more information: [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), and [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).
- Raw signature content has been exposed in `SignatureField`. Review the following API references for more information: [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), and [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).

#### Fixed

- Previously, the color space was not properly copied when cloning the PDF document.

### 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

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.

### 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 are now rendered correctly.

### Version 1.6

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 sample [Add data matrix to PDF](./code-samples/pdftools-sdk-toolbox-samples.mdx#add-data-matrix-to-pdf) now correctly places the matrix on the page.
- The Python code sample [Extract all text from PDF](./code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-text-from-pdf) now correctly reports page numbers when displaying extracted text to the console.

### Version 1.5

24 January 2025

#### Added

- The Toolbox add-on now natively supports Microsoft Windows ARM64 processor architecture.
- You can now copy a page without copying its graphical content using the new [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

28 November 2024

#### Added

- You can now 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.

- You can now 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

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.

- You can now 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

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. You can now 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

28 June 2024

#### Added

- It is now possible to retrieve information about a content element's Optional Content Membership using the Toolbox add-on for the Pdftools SDK. Optional Content Membership is defined by Optional Content Groups (also called layers) whose state determines whether a content element is visible or invisible.

- You can now retrieve the Rotation (`None`, `Clockwise`, `UpsideDown`, or `CounterClockwise`) of a page using the Toolbox add-on for the Pdftools SDK.

### Version 1.0

24 April 2024

#### Added

- Integrated the [Toolbox add-on](./getting-started/toolbox/README.mdx) into the Pdftools SDK. Now all the functionality from the PDF Toolbox SDK is included with your Pdftools SDK license.

## Pdftools SDK Shell Tool

### Version 1.8

19 June 2025

#### Added

- As of this update, text can now be extracted from PDFs.
- 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.

### Version 1.7

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

10 January 2025

#### Added

- Add a new method `AddAssociatedFile` that lets you to embed a file into a PDF. For more information, review the following 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)

#### 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)
- Pdftools SDK now natively supports Microsoft Windows ARM64 processor architecture.
- 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

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

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](./sign-and-secure/sign/README.mdx) 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

25 April 2024

#### Added

- Support for [mixed raster content](./optimize/optimization-profiles.mdx#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](./optimize/optimization-profiles.mdx#mixed-raster-content-optimization-profile) by using the `-drc` option when performing PDF optimization.

### Version 1.2

12 April 2024

#### Added

- Support PDF to PDF/A file conversion. All supported PDF and PDF/A versions are listed in [Supported PDF versions](README.mdx#supported-pdf-versions).
- Support PDF file validation of conformance with PDF or PDF/A standards listed in [Supported PDF versions](README.mdx#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

19 January 2024

#### Added

- Support for merging and splitting PDF files to assemble new output documents.
- Support for rendering a PDF files to an image suitable for fax, archiving, or viewing.

### Version 1.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, and the compression to minimize the file size.

---

## 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 is 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.

See the sections below for specific information about:

- [Signing PDF documents](sign/README.mdx)
- [PDF security](secure/README.mdx)

---

## 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](/docs/knowledge/pdf-a/).
:::

The encryption process applies encryption to all streams (e.g. 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](pdf-encryption.mdx)**.

:::tip Get started
Learn **[how to encrypt a PDF document](encrypt-a-pdf.mdx)** with the Pdftools SDK.
:::

---

## Encrypt and decrypt a PDF document

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The Pdftools SDK provides methods to open and save encrypted PDF documents.
The [PDF encryption process](pdf-encryption.mdx) applies encryption to all streams (e.g. 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.

## Opening an encrypted PDF document

:::note Quick start
Download the full sample in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Decrypt/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

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](pdf-encryption.mdx#permissions-and-passwords-in-pdf-documents).

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

In the Pdftools SDK, the password is provided as an optional parameter to the static `Document.Open` method.

```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
// 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`.

## Saving an encrypted PDF document

:::note Quick start
Download the full sample in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Encrypt/Download?technology=C).

Interested in other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

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, e.g. signing.

```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
// 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));
```

## Removing 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 as shown above, the document can be processed in the same way as for encryption, but setting the `Encryption` to `null`.

```csharp
// Create output options and remove encryption by setting it to null
var outOpt = new OutputOptions();
outOpt.Encryption = null;
```

```java
// Create output options and remove encryption by setting it to null
OutputOptions outOpt = new OutputOptions();
outOpt.setEncryption(null);
```

---

## 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 allows 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, delete pages, etc.)

## Reading 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.

## Encrypting 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](encrypt-a-pdf.mdx).
:::

## 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](#validating-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](/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](sign-document.mdx)** with a document approval signature.
:::

### Document certification signatures

Document certification signatures are also known as Modification Detection and Prevention (MDP) signatures.
This type of signatures 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](sign-certify.mdx)** 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](timestamp-authority.mdx).

:::tip Get started
Learn how to **[apply a digital time-stamp to a PDF document](sign-timestamp.mdx)** 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](cryptographic-providers.mdx).

## Embedding long-term validation information

To ensure a signature can be validated over time, [long-term validation information](long-term-validation.mdx) 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.
:::

## Signing 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](../../archive/archive-pdf-pdfa.mdx), 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](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.

## Validating 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](sign-validate.mdx)** in a document.
:::

## Creating a signature visual appearance

The Pdftools SDK allows for adding a [visual appearance](signature-appearance.mdx) 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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](#configuring-https-connections)
- Store certificates in a [local directory](#storing-local-certificates) recognized by the SDK
- Set up the SDK to route requests via a [proxy server](#using-a-proxy-server)

## Configuring 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:

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.

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/`

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.
:::

## Storing local certificates

When [signing PDF documents](sign-document.mdx), 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)](long-term-validation.mdx).

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:

```
%LOCALAPPDATA%\PDF Tools AG\Certificates

%ProgramData%\PDF Tools AG\Certificates
```

```
~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates

/usr/share/pdf-tools/Certificates
```

```
~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates
```

## Using 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)](timestamp-authority.mdx) to retrieve a time-stamp
- Connecting to an [online signing service](cryptographic-providers.mdx#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](provider-globalsign.mdx) or [Swisscom](provider-swisscom.mdx) 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](long-term-validation.mdx) information in the digital signatures, then the following MIME types must be supported:

- `application/ocsp-request`
- `application/ocsp-response`

---

## Cryptographic providers

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), e.g. 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](configure-digital-signing.mdx#storing-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](provider-builtin.mdx).
:::

## PKCS#11 provider

The PKCS#11 provider creates a session to a cryptographic device (HSM, USB token, etc.) 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](provider-pkcs11.mdx).
:::

## 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](provider-globalsign.mdx).
:::

### 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](provider-swisscom.mdx).
:::

---

## 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](sign-document.mdx).
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](sign-timestamp.mdx).

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](configure-digital-signing.mdx#configuring-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](configure-digital-signing.mdx#using-a-proxy-server), the following MIME types must be supported:

- `application/ocsp-request`
- `application/ocsp-response`

---

## Built-in cryptographic provider

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The `BuiltIn` cryptographic provider enables access to the cryptographic functions of the local operating system. For example, to [sign a document](sign-document.mdx).
No cryptographic hardware or external service is required, except for the optional `TimestampUrl` used when appling a [time-stamp](sign-timestamp.mdx).

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](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-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](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Initializing 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.

```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

```

```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```

## Reading 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.

```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```

```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`, please refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html).
:::

## Adding long-term validation information

As an optional step, [long-term validation](long-term-validation.mdx) 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.

```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```

```java
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```

## Opening and signing 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.

```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
// 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

```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
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](../../archive/archive-pdf-pdfa.mdx), 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](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::

---

## GlobalSign cryptographic provider

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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](sign-document.mdx).
This provider requires a GlobalSign DSS account.
Accounts with static and dynamic identities are supported.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/GlobalSignDssSign/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

The GlobalSign DSS provides signing certificates and basic cryptographic (PKCS#1) signatures.
Additional certificates such as issuer certificates are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-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](#configuring-the-http-client-handler).
2. [Connect to GlobalSign DSS](#connecting-to-globalsign-dss).
3. [Create the document signature](#creating-the-document-signature).
4. [(Optional) Add long-term validation information](#adding-long-term-validation-information).
5. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Configuring 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.

```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
// 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);
}
```

## Connecting 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, i.e. 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.

```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
Session session = new Session(new URI("https://emea.api.dss.globalsign.com:8443"), apiKey, apiSecret, httpClientHandler);
```

## Creating 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.
:::

```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
// 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));
```

## Adding long-term validation information

As an optional step, [long-term validation](long-term-validation.mdx) 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.

```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```

```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(ValidationInformation.EMBED_IN_DOCUMENT);
```

## Opening and signing 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.

```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
// 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

```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
// 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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](sign-document.mdx).
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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pkcs11Sign/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

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](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-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](#loading-the-pkcs11-driver-module).
2. [Log in to the PKCS#11 device](#logging-in-to-the-pkcs11-device).
3. [Create the document signature](#creating-the-document-signature).
4. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Loading 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.

```csharp
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
using var module = Pkcs11.Module.Load(moduleName);

```

```java
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
Module module = Module.load(pkcs11Library);
```

## Logging 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.

```csharp
// Create a session to the cryptographic device and log in
// with the password (pin)
using var session = module.Devices.GetSingle().CreateSession(password);
```

```java
// Create a session to the cryptographic device and log in
// with the password (PIN)
Session session = module.getDevices().getSingle().createSession(password));
```

## Creating 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.

```csharp
// Create the signature configuration
// This can be re-used to sign multiple documents
var signature = session.CreateSignatureFromName(certificate);
```

```java
// Create the signature configuration
// This can be re-used to sign multiple documents
var signature = session.createSignatureFromName(certificate);
```

## Opening and signing 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.

```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
// 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

```csharp
// Load the PKCS#11 driver module (middleware)
// The module can only be loaded once in the application.
using var module = Pkcs11.Module.Load(moduleName);

// 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
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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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](sign-document.mdx).
This provider requires a Swisscom Signing Service account.
Accounts with static and on-demand identities are supported.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SwisscomSigSrvSign/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

The Swisscom Signing Service provides signing certificates using CMS (PKCS#7) signatures.
Additional certificates (for example, issuer certificates) are stored in the [Certificates directory](configure-digital-signing.mdx#storing-local-certificates).
These certificates are required when adding validation information to signatures that do not have the full trust chain embedded.
The [Certificates directory](configure-digital-signing.mdx#storing-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](#configuring-the-http-client-handler).
2. [Connect to Swisscom Signing Service](#connecting-to-swisscom-signing-service).
3. [Create the document signature](#creating-the-document-signature).
4. [(Optional) Add long-term validation information](#adding-long-term-validation-information).
5. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Configuring 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.

```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
// 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);
}
```

## Connecting 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.

```csharp
// Connect to the Swisscom Signing Service
using var session = new SwisscomSigSrv.Session(new Uri("https://ais.swisscom.com"), httpClientHandler);
```

```java
Session session = new Session(new URI("https://ais.swisscom.com"), httpClientHandler);
```

## Creating 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.
:::

```csharp
// Create a signing certificate for a static identity
var signature = session.CreateSignatureForStaticIdentity(identity, commonName);

```

```java
// Create a signing certificate for a static identity
// This can be re-used to sign multiple documents
SignatureConfiguration signature = session.createSignatureForStaticIdentity(identity, commonName);
```

## Adding long-term validation information

As an optional step, [long-term validation](long-term-validation.mdx) 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.

```csharp
// Embed validation information to enable the long term validation (LTV) of the signature (default)
signature.EmbedValidationInformation = true;
```

```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setEmbedValidationInformation(true);
```

## Opening and signing 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.

```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

// 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

```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
// 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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInCertify/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

In this example, the [Built-in cryptographic provider](provider-builtin.mdx) 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](cryptographic-providers.mdx) can be used to apply a document certification signature.
:::

**Steps to certify a document**:

1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [(Optional) Add user modification permissions](#adding-user-modification-permissions)
5. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Initializing the cryptographic provider

When using the [Built-in cryptographic provider](provider-builtin.mdx), 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.

```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

```

```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```

## Reading 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.

```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```

```java
// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
```

## Adding long-term validation information

As an optional step, [long-term validation](long-term-validation.mdx) 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.

```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```

```java
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```

## Adding 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.

```csharp
// Assign Form Filling user permissions to the document
var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling);
```

```java
// Assign form filling user permissions to the document
MdpPermissionOptions permissions = new MdpPermissionOptions(MdpPermissions.FORM_FILLING);
```

## Opening and signing 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.

```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
// 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

```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
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 = new 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](signature-appearance.mdx) page.
:::

:::note Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), 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](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::

---

## Sign a PDF document

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=C).

Interested in other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

In this example, the [Built-in cryptographic provider](provider-builtin.mdx) 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](cryptographic-providers.mdx) can be used to apply a document approval signature.
:::

**Steps to sign a document**:

1. [Initialize the cryptographic provider](#initializing-the-cryptographic-provider).
2. [Read the PFX or P12 certificate](#reading-the-pfx-or-p12-certificate).
3. [(Optional) Add long-term validation information](#adding-long-term-validation-information)
4. [Open and sign the document](#opening-and-signing-the-document).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Initializing the cryptographic provider

When using the [Built-in cryptographic provider](provider-builtin.mdx), 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.

```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

```

```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```

## Reading 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.

```csharp
// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);
```

```java
// Create signature configuration from PFX (or P12) file
FileStream pfxStr = new FileStream(certificateFile, FileStream.Mode.READ_ONLY));
SignatureConfiguration signature = session.createSignatureFromCertificate(pfxStr, password);
```

## Adding long-term validation information

As an optional step, [long-term validation](long-term-validation.mdx) 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.

```csharp
// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;
```

```java
// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.setValidationInformation(com.pdftools.crypto.ValidationInformation.EMBED_IN_DOCUMENT);
```

## Opening and signing 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.

```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
// 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

```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
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](../../archive/archive-pdf-pdfa.mdx), 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](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::

---

## Add a document time-stamp

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInAddTimestamp/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

The time-stamp is provided by a [time-stamp authority](timestamp-authority.mdx) (TSA) that is configured in the cryptographic provider.
In this example, the [Built-In cryptographic provider](provider-builtin.mdx) 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](#initializing-the-cryptographic-provider).
2. [Connect to the time-stamp authority](#connecting-to-the-time-stamp-authority).
3. [Add the document time-stamp](#adding-the-document-time-stamp).

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Initializing the cryptographic provider

When using the [Built-In cryptographic provider](provider-builtin.mdx), 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.

```csharp
// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

```

```java
// Create a session to the built-in cryptographic provider
Provider session = new Provider();
```

## Connecting to the time-stamp authority

For the [Built-In](../provider-builtin) and [PKCS#11](provider-pkcs11.mdx) cryptographic providers, a third-party time-stamp authority must be configured.
To do this, you pass [the URL of the time-stamp authority](timestamp-authority.mdx#time-stamp-authority-uri) to the cryptographic provider and call the `CreateTimestamp` method.

```csharp
// Create time-stamp configuration
session.TimestampUrl = timeStampUrl;
var timestamp = session.CreateTimestamp();
```

```java
// Create time-stamp configuration
session.setTimestampUrl(timeStampUrl);
TimestampConfiguration timestamp = session.createTimestamp();
```

## Adding 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.

```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 = new Signer().AddTimestamp(inDoc, timestamp, outStr);
```

```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.addTimestamp(inDoc, signature, outStr);
```

## Full example

```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
// 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](signature-appearance.mdx) page.
:::

:::note Signing PDF/A documents
During the [conversion process from PDF to PDF/A](../../archive/archive-pdf-pdfa.mdx), 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](../../archive/archive-pdf-pdfa.mdx) before any digital signatures are applied.
:::

---

## Validate signatures in a signed PDF document

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The Pdftools SDK lets you validate digital signatures that have been added to [approve](sign-document.mdx) or [certify](sign-certify.mdx) 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

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/SignaturesValidate/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

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](#creating-a-validator-object).
2. [Configure the validation parameters](#configuring-the-validation-parameters).
3. [(Optional) Add certificates for offline validation](#adding-certificates-for-offline-validation).
4. [Open and validate the document](#opening-and-validating-the-document).
5. [Check and output the results](#checking-and-outputting-the-results)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Creating 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](#configuring-the-validation-parameters) and calculate the overall validation result.

 

```csharp
// Create a Validator object
var validator = new Validator();
```

```java
// Create a Validator object
Validator validator = new Validator();
```

## Configuring 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`.

 

```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
// 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`.
:::

## Adding certificates for offline validation
Certificate files (e.g. PFX or CER) from the local file system can be added as trusted sources using a `CustomTrustList`.

 

```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
// 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, e.g. `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` please refer to the [Java API Reference](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html).
:::

## Opening and validating 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.

 

```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
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);
```

## Checking and outputting the results

### Checking 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.

 

```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);
    Console.WriteLine();
}
```

:::note
To implement `PrintContent`, see [print and to string functions](#print-and-to-string-functions).
:::

```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());
    System.out.println();
});
```

:::note
To implement `printContent`, see [print and to string functions](#print-and-to-string-functions).
:::

### Checking 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.

 

```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
validator.addConstraintListener(e -> {
    System.out.println("  - " + e.getSignature().getName() + (e.getDataPart().length() > 0 ? (": " + e.getDataPart()) : "") + ": " + 
        constraintToString(e.getIndication(), e.getSubIndication(), e.getMessage()));
});
```

:::note
To implement `constraintToString`, see [print and to string functions](#print-and-to-string-functions).
:::

## Full example

 

```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);
        Console.WriteLine();
    }

    return 0;
}
catch (Exception ex)
{
    Console.WriteLine("Unable to validate file: " + ex.Message);
    return 5;
}
```

```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()));
});

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());
        }

        printContent(result.getSignatureContent());
        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. 

 

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)
{
    if(content != null)
    {
        Console.WriteLine("  - Validity  : " + ConstraintToString(content.Validity));
        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);
                    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));
    }
    else
    {
        Console.WriteLine("    - null");
    }
}

private static String ConstraintToString(ConstraintResult constraint)
{
    return ConstraintToString(constraint.Indication, constraint.SubIndication, constraint.Message);
}

private static String ConstraintToString(Indication indication, SubIndication subIndication, String message)
{
    return (indication == Indication.Valid ? "" : (indication == Indication.Indeterminate ? "?" : "!")) + "" +
        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);
}
```

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)
{        
    if(content != null)
    {
        System.out.println("  - Validity  : " + constraintToString(content.getValidity()));
        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());
                    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()));
    }
    else
    {
        System.out.println("    - null");
    }
}

private static String constraintToString(ConstraintResult constraint)
{
    return constraintToString(constraint.getIndication(), constraint.getSubIndication(), constraint.getMessage());
}

private static String constraintToString(Indication indication, SubIndication subIndication, String message)
{
    return (indication == Indication.VALID ? "" : (indication == Indication.INDETERMINATE ? "?" : "!")) + "" +
        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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/VisualSignature/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/) and we'll add it to our samples backlog.
:::

:::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

  
  
  
  
    Signed by: Max Muster
  
  
    Signing date: [signature:date,localtime,%d.%m.%Y %H:%M:%S]
  
  
    Company: [custom:company]
  
  
    Powered by:
  

```

```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](pathname:///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:

```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
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 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](sign-document.mdx).
:::

```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
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](sign-document.mdx).
:::

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.

```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
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

---

## 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](provider-globalsign.mdx) and [Swisscom](provider-swisscom.mdx) cryptographic providers have their own TSA with which the user can generate trusted time-stamp information.
The [Built-in](provider-builtin.mdx) and [PKCS#11](provider-pkcs11.mdx) 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](sign-timestamp.mdx), 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](configure-digital-signing.mdx#configuring-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](configure-digital-signing.mdx#using-a-proxy-server) is used, the following MIME types must be supported:

- `application/timestamp-query`
- `application/timestamp-reply`

---

## Add and fill form fields

The Toolbox add-on lets you add and fill form fields in PDF documents.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## 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](../../code-samples/pdftools-sdk-toolbox-samples/#add-form-field) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddFormFields/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddFormFields/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Fill form fields
You can learn how to fill form fields in a PDF document using out [Fill Form Fields](../../code-samples/pdftools-sdk-toolbox-samples/#fill-form-fields) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FillFormFields/Download?technology=C).
:::

---

## Manage annotations

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Java).

Interested in C, Python, Go, or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our samples backlog.
:::

The Toolbox add-on supports the following 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. [Reading the input document](#reading-the-input-document)
2. [Copying document-wide data](#copying-document-wide-data)
3. [Copying and annotating the input pages](#copying-and-annotating-the-input-pages)
4. [Adding copied pages to the output document](#adding-copied-pages-to-the-output-document)
5. [Full example](#full-example)

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-toolbox-add-on-license)**.

:::

## Reading 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.

```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
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)) {
```

## Copying 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.

```csharp
// Copy document-wide data
CopyDocumentData(inDoc, outDoc);
```

```java
// Copy document-wide data
copyDocumentData(inDoc, outDoc);
```

CopyDocumentData function

```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
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));
}
```

## Copying and annotating 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.

```csharp
// Define page copy options
PageCopyOptions copyOptions = new PageCopyOptions();

// Copy first page and add annotations
Page outPage = CopyAndAddAnnotations(outDoc, inDoc.Pages[0], copyOptions);
```

```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

```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
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;
}
```

## Adding 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).

```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
// 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

Download the full example in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Java).

---

## Add and remove content

The Toolbox add-on lets you add content to a PDF such as text, watermarks, barcodes, and images.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## Content types
The Toolbox add-on supports adding the following types of content:

- `Text`
- `Image`
- `Image Mask`
- `Path`

## Add and remove content
There is a wide range of use cases for the following content types:

| Content type    | Use case example       |
| --------------- | ---------------------- |
| Text            | [Add text to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-text-to-pdf)[Add a barcode to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-barcode-to-pdf)[Add line numbers to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-line-numbers-to-pdf)[Add a stamp to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-stamp-to-pdf)[Add page numbers to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#stamp-page-number-to-pdf) [Layout text in a PDF page](../code-samples/pdftools-sdk-toolbox-samples.mdx#layout-text-on-pdf-page) [Remove glyphs from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#remove-glyphs) [Remove white text from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#remove-white-text-from-pdf) |
| Image           | [Add a QR code (Data Matrix) to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-data-matrix-to-pdf)[Add an image to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-image-to-pdf)  |
| Image Mask      | [Add an image mask to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-image-mask-to-pdf) |
| Path            | [Add a vector graphic to a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-vector-graphic-to-pdf) |

:::note Quick start - Add text to a PDF
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddText/Download?technology=C).
:::

---

## 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.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## Extract text
Learn how to extract text content from a PDF document using the [Extract all text from PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-text-from-pdf) sample project. This project also illustrates the use of heuristics to assemble text content into words and sentences based on their position on the page.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TextExtraction/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/TextExtraction/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Extract images
Learn how to extract images from a PDF document using the [Extract all images and image masks from a PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#extract-all-images-and-image-masks-from-a-pdf) sample project. 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
:::

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ImageExtraction/Download?technology=C).
:::

## Extract signatures
Learn how to extract signature content from a PDF document using the [List Signatures in PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-signatures-in-pdf) sample project. You can automatically extract signature information such as name, date, and contact information.

For a guide to comprehensive validation of digital signatures, review the [Validate signatures in a signed PDF document](../sign-and-secure/sign/sign-validate.mdx) page.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListSignatures/Download?technology=C).
:::

## Extract document attributes and metadata
You can learn how to extract document attributes and metadata from a PDF document using our [List document information of PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-document-information-of-pdf) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=C).
:::

---

## Generate PDFs

The Toolbox add-on lets you create a new PDF files from scratch using Java, .Net, and C. 
After creating the PDF files, use the Toolbox add-on to [add content](./edit.mdx), [add form fields](./add-and-fill-form-fields.mdx), [manage metadata](./manage-metadata.mdx), and more.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## Create a new PDF document
Learn how to create a new PDF file using [Layout text on PDF page](../code-samples/pdftools-sdk-toolbox-samples.mdx#layout-text-on-pdf-page) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/LayoutText/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/LayoutText/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

---

## 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.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## List document metadata
Learn how to list document attributes and metadata from a PDF document using the [List document information of PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#list-document-information-of-pdf) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/ListInfo/Download?technology=C).
:::

## Add metadata
Learn how to set metadata such as the author, title, and creator of a PDF document using the [Add metadata to PDF](../code-samples/pdftools-sdk-toolbox-samples.mdx#add-metadata-to-pdf) sample project. Optionally, copy metadata from another PDF document or the content of an XMP metadata file.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/AddMetadata/Download?technology=C).
:::

---

## 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.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## Flatten form fields
You can learn how to flatten form fields in a PDF document using our [Flatten form fields](../code-samples/pdftools-sdk-toolbox-samples.mdx#flatten-form-fields-in-pdf) sample project. This process turns the form field into non-interactive content while retaining its visual appearance.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FlattenFormFields/Download?technology=C).
:::

## Set page dimensions
Learn how to set the dimensions of a PDF page using the [Fit pages to specific page format](../code-samples/pdftools-sdk-toolbox-samples.mdx#fit-pages-to-specific-page-format) sample project. 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.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/FitPage/Download?technology=C).
:::

## Set page orientation
Learn how to adjust the orientation of a PDF page using the [Set page orientation](../code-samples/pdftools-sdk-toolbox-samples.mdx#set-page-orientation) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RotatePages/Download?technology=C).
:::

## 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](../code-samples/pdftools-sdk-toolbox-samples.mdx#place-multiple-pages-on-one-page) sample project.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/MultipleUp/Download?technology=C).
:::

---

## 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.

:::info
This functionality is part of the Toolbox add-on, a separate SDK that you can use with the same license key as the Pdftools SDK. To use and integrate this add-on, review [Getting started with the Toolbox add-on](../../getting-started/toolbox/) and [Toolbox add-on code samples](../code-samples/pdftools-sdk-toolbox-samples.mdx).
:::

## Remove pages
Learn how to remove specific pages from a PDF document using the [Remove pages from PDF](../../code-samples/pdftools-sdk-toolbox-samples/#remove-pages-from-pdf) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/Split/Download?technology=C).
:::

## Remove content
Learn how to iterate through the PDF to remove specific content using the [Remove White Text from PDF](../../code-samples/pdftools-sdk-toolbox-samples/#remove-white-text-from-pdf) sample project. 

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveWhiteText/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveWhiteText/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our sample backlog.
:::

## Remove individual characters (glyphs)
Learn how to remove individual characters (glyphs) from text in a PDF document using the [Remove glyphs](../../code-samples/pdftools-sdk-toolbox-samples/#remove-glyphs) code sample.

:::note Quick start
Download the full sample now in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveGlyphs/Download?technology=CS) and [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDKXT/RemoveGlyphs/Download?technology=Java).

Interested in C or other language samples? Let us know on the [contact page](https://www.pdf-tools.com/contact/), and we'll add it to our samples backlog.
:::

---

## 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](conformance-levels.mdx)** 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](validation-checks.mdx)** 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 (e.g. standard image resolution) can occur at the same time.

:::tip Get started
Learn **[how to validate a PDF document](validate-a-pdf.mdx)** for conformance with a PDF version, or a PDF/A standard and level.
:::

---

## Conformance levels

Conformance levels apply to [PDF/A documents](/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](validation-checks.mdx).
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](/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](/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](/docs/knowledge/pdf-a/#pdfa-2) and [PDF/A-3](/docs/knowledge/pdf-a/#pdfa-3).

---

## Reporting levels for validation



---

## Validate PDF document

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

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.

:::note Quick start
Download the full sample in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=Java), and [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=C).
:::

**Steps to validate a document**:

1. [Reading the input document](#reading-the-input-document)
2. [Creating a Conformance object](#creating-a-conformance-object)
3. [Creating a Validator object](#creating-a-validator-object)
4. [Running the Validate process](#running-the-validate-process)
5. [Full example](#full-example)

---

:::note Before you begin
You need to **[initialize the library](/docs/licenses/products/pdf-tools-sdk-license/#activate-the-pdftools-sdk-license)**.

:::

## Reading 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 `Converter`.

```csharp
// Open image document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);
```

```java
// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
com.pdftools.pdf.Document inDoc = com.pdftools.pdf.Document.open(inStr);
```

## Creating 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](validation-checks.mdx)**.
:::

This example uses the PDF/A-2 standard (`2`), with conformance level B (`Conformance.PdfALevel.B`).

```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
// 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));
```

## Creating 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.

```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 ? " " + e.PageNo : "");
```

```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()) : "")
);
```

## Running 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.
:::

```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
// 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

```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 ? " " + 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
// 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](/docs/knowledge/pdf-standards)** and **[conformance level](conformance-levels.mdx)**.

|                                                                                              | PDF | PDF/A-1 | PDF/A-2 & PDF/A-3 | Level U | Level A |
| -------------------------------------------------------------------------------------------- | --- | ------- | ----------------- | ------- | ------- |
| **Lexical checks**                                                                           |     |         |                   |         |         |
| Structure of tokens such as keywords, names, numbers, strings etc.                           | x   | x       | x                 | x       | x       |
| Structure of the cross-reference table                                                       | x   | x       | x                 | x       | x       |
| File positions in the trailer dictionary, cross reference table, etc.                        | 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, streams, etc.                           | x   | x       | x                 | x       | x       |
| Compression errors, e.g. CCITT, JPEG, Flate, etc.                                            | 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, e.g. 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, e.g. page objects                               | x   | x       | x                 | x       | x       |
| Type of the dictionary entry's value, e.g. integer, string, name                             | x   | x       | x                 | x       | x       |
| Whether the object must be indirect or direct, e.g. 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, e.g. if an image has a stencil mask and soft mask at the same time | x   | x       | x                 | x       | x       |
| Conformance to implementation limits defined by the PDF Reference                            | x   | x       | x                 | x       | x       |
| No unredered 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, reference XObjects, etc.)            |     | 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       |

---

## PDF Viewer SDK

import ViewerPricing from '/src/modules/reference/ref_viewer-pricing-table.mdx';

Integrate a comprehensive PDF viewer with editing capabilities into your web applications. The PDF Viewer SDK is a development library for TypeScript compatible with multiple frameworks and browsers.

## 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:

- View PDF files.
- Search PDF files.
- Navigate, and work with PDF files programmatically.

The PDF Viewer SDK consists of two npm packages, the PDF Web Viewer and the PDF Web SDK:
- [PDF Web Viewer](#pdf-web-sdk)
- [PDF Web SDK](#pdf-web-sdk)

### PDF Web Viewer

The [PDF Web Viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) lets you implement PDF viewer capabilities with search.

:::tip Get started
Try it out with **[Getting started with the PDF Viewer SDK](./getting-started/README.mdx)**.
:::

### PDF Web SDK

The [PDF Web SDK](https://www.npmjs.com/package/@pdftools/pdf-web-sdk) provides the functionality required by the PDF Viewer SDK package with some additional features.
You can use it to implement a viewer with highly customizated experience or to automate processes around your documents programmatically, directly from your TypeScript project without the need for a GUI.
It serves also as the SDK layer for the underlying web assembly that contains the SDK logic and is both consumed by the PDF Web Viewer and the PDF Web SDK.

:::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](./guides/README.mdx)**.
:::

### License overview

## Supported languages and frameworks

The PDF Viewer SDK is provided in TypeScript and compatible with the following programming languages, libraries, and frameworks:

- TypeScript
- JavaScript
- React
- 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](/docs/pdf-tools-sdk/)
- [Conversion Service](/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](../README.mdx#pdf-web-viewer)   | [@pdftools/pdf-web-viewer](https://www.npmjs.com/package/@pdftools/pdf-web-viewer) | [Viewer API reference](./viewer/index.md) |
|     2 | [PDF Web SDK](../README.mdx#pdf-web-sdk) | [@pdftools/pdf-web-sdk](https://www.npmjs.com/package/@pdftools/pdf-web-sdk)       | [PDF Web SDK API reference](./web-sdk/index.md) |

The following chart gives an overview of the most important components in the PDF Viewer SDK and the PDF Web SDK.

![Viewer Architecture Overview](/img/viewer-architecture-overview.png)

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](../getting-started/README.mdx).
:::

### Important components

There are two components which are relevant to interact with the PDF Viewer SDK.

#### PdfToolsViewer

The `PdfToolsViewer` provides access to the initializer `PdfToolsViewer.initialize();` which returns the element to attach to a page.

#### PdfToolsViewerApi

[`PdfToolsViewerApi`](./viewer/interfaces/PdfToolsViewerApi.md) singleton object allows basic programmatic access to the PDF Viewer SDK, for example to programmatically open a document or control the toolbar. 

## 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](../guides/document-view.mdx).
:::

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`](./web-sdk/variables/pdfToolsWebSdk.md) 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`](./web-sdk/namespaces/Pdf/classes/Controller.md) 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`](./web-sdk/namespaces/Pdf/classes/Document.md) 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`](./web-sdk/namespaces/Pdf/classes/Controller.md).

#### Pdf.Page

[`Pdf.Page`](./web-sdk/namespaces/Pdf/classes/Page.md) 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`](./web-sdk/namespaces/Pdf/classes/Document.md) property called `pages`.

#### Pdf.AnnotationManager

[`Pdf.AnnotationManager`](./web-sdk/namespaces/Pdf/classes/AnnotationManager.md) 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`](./web-sdk/namespaces/Pdf/classes/Document.md) property called `annotations`.

#### UI.DocumentView

[`UI.DocumentView`](./web-sdk/namespaces/UI/classes/DocumentView.md) 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`](./web-sdk/namespaces/Pdf/classes/Document.md) in order to create an interactive preview of the PDF document.

---

## Enumeration: FitMode

# 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: PageLayoutMode

# 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: Rotation

# 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).

---

## @pdftools/pdf-web-viewer

# @pdftools/pdf-web-viewer

## Other

- [FitMode](enumerations/FitMode.md)
- [PageLayoutMode](enumerations/PageLayoutMode.md)
- [Rotation](enumerations/Rotation.md)
- [HideableComponentConfigName](type-aliases/HideableComponentConfigName.md)

## PdfToolsViewerApi

- [PdfToolsViewerApi](interfaces/PdfToolsViewerApi.md)

## PdfToolsViewerApi.contextualMenus

- [ContextualMenus](interfaces/ContextualMenus.md)

## PdfToolsViewerApi.dialogs

- [Dialogs](interfaces/Dialogs.md)

## PdfToolsViewerApi.document

- [Document](interfaces/Document.md)

## PdfToolsViewerApi.documentView

- [DocumentView](interfaces/DocumentView.md)

## PdfToolsViewerApi.file

- [Files](interfaces/Files.md)

## PdfToolsViewerApi.search

- [Search](interfaces/Search.md)

## PdfToolsViewerApi.stampAnnotations

- [StampAnnotations](interfaces/StampAnnotations.md)

## PdfToolsViewerApi.stickyNotes

- [StickyNotes](interfaces/StickyNotes.md)

## PdfToolsViewerApi.toolbar

- [Toolbar](interfaces/Toolbar.md)

## PdfToolsViewerApi.topbar

- [Topbar](interfaces/Topbar.md)

---

## Interface: ContextualMenus

# Interface: ContextualMenus

Groups all the API actions related to the contextual menus.

## Properties

### annotation

> **annotation**: `object`

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggled"`

• **callback**

##### Returns

`void`

#### deleteButton

> **deleteButton**: `object`

#### deleteButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### deleteButton.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### editButton

> **editButton**: `object`

#### editButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### editButton.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### emitToggled()

> **emitToggled**: (`active`, `options`?) => `void`

##### Parameters

• **active**: `boolean`

• **options?**: `ContextualMenuOptions`

##### Returns

`void`

#### lockButton

> **lockButton**: `object`

#### lockButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### lockButton.emitClicked()

> **emitClicked**: (`options`) => `void`

##### Parameters

• **options**: `StickyNoteModalOptions`

##### Returns

`void`

---

## Interface: Dialogs

# Interface: Dialogs

Groups all the API actions related to dialogs in the Viewer.

## Properties

### passwordModal

> **passwordModal**: `object`

Groups all the API actions related to the password modal dialog.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggled"`

• **callback**

##### Returns

`void`

#### emitToggled()

> **emitToggled**: (`active`) => `void`

##### Parameters

• **active**: `boolean`

##### Returns

`void`

#### unlockButton

> **unlockButton**: `object`

#### unlockButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### unlockButton.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

***

### thumbnailsSidebar

> **thumbnailsSidebar**: `object`

Groups all the API actions related to the thumbnails sidebar dialog.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the thumbnail click event.

##### Parameters

• **eventName**: `"thumbnailClicked"`

The event name to listen for (e.g., `'thumbnailClicked'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.dialogs.thumbnailsSidebar.addEventListener('thumbnailClicked', () => { console.log('callback') });```

#### emitThumbnailClicked()

> **emitThumbnailClicked**: (`pageNumber`) => `void`

Triggered when a thumbnail in the sidebar is clicked.

##### Parameters

• **pageNumber**: `number`

The page number of the clicked thumbnail.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.dialogs.thumbnailsSidebar.emitThumbnailClicked(4);```

---

## Interface: Document

# Interface: Document

Groups all the API actions related to document handling.

## Properties

### goToPage()

> **goToPage**: (`viewerEl`, `pageNumber`) => `void`

Triggers an event to navigate to a specific page in the document.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **pageNumber**: `number`

The page number to navigate to.

#### Returns

`void`

#### Example

```const viewerEl = document.querySelector('#viewer'); PdfToolsViewerApi.document.goToPage(viewerEl, 2);```

***

### nextPage()

> **nextPage**: (`viewerEl`) => `void`

Triggers an event to navigate to the next page in the document.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

#### Returns

`void`

#### Example

```const viewerEl = document.querySelector('#viewer'); PdfToolsViewerApi.document.nextPage(viewerEl);```

***

### open()

> **open**: (`inputDocument`) => `void`

Opens a document.

#### Parameters

• **inputDocument**: `InputFile` \| `InputUri`

The input required to open the document (either `Pdf.InputFile` or `Pdf.InputUri`).

#### Returns

`void`

#### Example

```PdfToolsViewerApi.document.tools.open({ data: file });```

***

### previousPage()

> **previousPage**: (`viewerEl`) => `void`

Triggers an event to navigate to the previous page in the document.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

#### Returns

`void`

#### Example

```const viewerEl = document.querySelector('#viewer'); PdfToolsViewerApi.document.previousPage(viewerEl);```

***

### rotate()

> **rotate**: (`viewerEl`, `newRotation`) => `void`

Triggers an event to rotate the document.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **newRotation**: [`Rotation`](../enumerations/Rotation.md)

The new rotation value to apply.

#### Returns

`void`

#### Example

```const viewerEl = document.querySelector('#viewer'); PdfToolsViewerApi.document.rotate(viewerEl, Rotation.Clockwise);```

***

### save()

> **save**: (`viewerEl`, `options`) => `void`

Saves the current document as a PDF file and triggers a download.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **options**: `DocumentSaveOptions`

Options for configuring the document save behavior.

#### Returns

`void`

#### Example

```const viewerEl = document.querySelector('#viewer'); PdfToolsViewerApi.document.save(viewerEl, options);```

***

### tools

> **tools**: `object`

Groups all the API actions related to document tools.

#### extractText

> **extractText**: `object`

Groups all the API actions related to document text extraction tools.

#### extractText.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the different events related to text extraction.

##### Parameters

• **eventName**: `"start"` \| `"textExtracted"`

The event name (`'start'` or `'textExtracted'`).

• **callback**: () => `string` \| (`txt`) => `void`

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.document.tools.extractText.addEventListener('start', () => { console.log('callback') });```

#### extractText.emitStart()

> **emitStart**: () => `void`

Triggers an event indicating that text extraction has started.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.document.tools.extractText.emitStart();```

#### extractText.emitTextExtracted()

> **emitTextExtracted**: (`txt`) => `void`

Triggers an event indicating that text has been extracted.

##### Parameters

• **txt**: `string`

The extracted text.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.document.tools.extractText.emitTextExtracted('lorem ipsum');```

---

## Interface: DocumentView

# Interface: DocumentView

Groups all the API actions related to the document view.

## Properties

### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

#### Parameters

• **eventName**: `"clicked"` \| `"doubleclicked"` \| `"setCursor"`

• **callback**: (`pageNumber`, `point`) => `void` \| (`pageNumber`, `point`) => `void` \| (`cursor`) => `void`

#### Returns

`void`

***

### emitClicked()

> **emitClicked**: (`pageNumber`, `point`) => `void`

#### Parameters

• **pageNumber**: `number`

• **point**: `Point`

#### Returns

`void`

***

### emitDoubleclicked()

> **emitDoubleclicked**: (`pageNumber`, `point`) => `void`

#### Parameters

• **pageNumber**: `number`

• **point**: `Point`

#### Returns

`void`

***

### emitSetCursor()

> **emitSetCursor**: (`cursor`) => `void`

#### Parameters

• **cursor**: `Cursor`

#### Returns

`void`

---

## Interface: Files

# Interface: Files

Groups all the API actions related to file handling.

## Properties

### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener for the 'opened' event when a file is opened.

#### Parameters

• **eventName**: `"opened"`

The event name (e.g., `'opened'`).

• **callback**

The callback function to execute when the event is triggered.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.file.addEventListener('opened', () => { console.log('callback') });```

***

### emitOpened()

> **emitOpened**: (`inputDocument`) => `void`

Triggers an event indicating that a file has been opened.

#### Parameters

• **inputDocument**: `InputFile` \| `InputUri`

#### Returns

`void`

#### Example

```PdfToolsViewerApi.file.emitOpened('https://example.com/file.pdf');```

---

## Interface: PdfToolsViewerApi

# Interface: PdfToolsViewerApi

API for interacting with the PDF Viewer, exposing core functionalities for document interaction, event handling, and UI management.

## Other

### stampAnnotations

> **stampAnnotations**: [`StampAnnotations`](StampAnnotations.md)

Groups all the stamp annotations-related API actions.

#### Catergory

stampAnnotations

***

### stickyNotes

> **stickyNotes**: [`StickyNotes`](StickyNotes.md)

Groups all the sticky notes-related API actions.

#### Catergory

stickyNotes

## PdfToolsViewerApi

### hideElements()

> **hideElements**: (`viewerEl`, `components`) => `void`

Hides specified UI elements in the Viewer.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **components**: [`HideableComponentConfigName`](../type-aliases/HideableComponentConfigName.md)[]

List of components to hide.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.hideElements(['icon-button-print']);```

***

### showElements()

> **showElements**: (`viewerEl`, `components`) => `void`

Shows specified UI elements in the Viewer.

#### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **components**: [`HideableComponentConfigName`](../type-aliases/HideableComponentConfigName.md)[]

List of components to show.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.showElements(['toolbar', 'icon-button-hamburger']);```

## contextualMenus

### contextualMenus

> **contextualMenus**: [`ContextualMenus`](ContextualMenus.md)

Groups all the contextual menu-related API actions.

## dialogs

### dialogs

> **dialogs**: [`Dialogs`](Dialogs.md)

Groups all the dialog-related API actions.

## document

### document

> **document**: [`Document`](Document.md)

Groups all the document-related API actions.

## documentView

### documentView

> **documentView**: [`DocumentView`](DocumentView.md)

Groups all the documentView-related API actions.

## file

### file

> **file**: [`Files`](Files.md)

Groups all the file-related API actions.

## search

### search

> **search**: [`Search`](Search.md)

Groups all the search-related API actions.

## toolbar

### toolbar

> **toolbar**: [`Toolbar`](Toolbar.md)

Groups all the toolbar-related API actions.

## topbar

### topbar

> **topbar**: [`Topbar`](Topbar.md)

Groups all the topbar-related API actions.

---

## Interface: Search

# Interface: Search

Groups all the API actions related to search functionality.

## Properties

### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the different search events.

#### Parameters

• **eventName**: `"toggled"` \| `"searchResultClicked"` \| `"settingsClicked"` \| `"caseSensitiveToggled"` \| `"regularExpressionToggled"` \| `"clearSearchPanelInputClicked"`

The event name (e.g., `'toggled'`, `'searchResultClicked'`, etc.).

• **callback**: (`active`) => `void` \| (`searchResult`) => `void` \| () => `void` \| (`caseSensitive`) => `void` \| (`regularExpression`) => `void` \| () => `void`

The callback function to execute when the event is triggered.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.addEventListener('toggled', () => { console.log('callback') });```

***

### emitCaseSensitiveToggled()

> **emitCaseSensitiveToggled**: (`caseSensitive`) => `void`

Triggers an event indicating that the search case-sensitive checkbox has been toggled.

#### Parameters

• **caseSensitive**: `boolean`

`true` if case sensitivity has been enabled, `false` otherwise.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitCaseSensitiveToggled(false);```

***

### emitClearSearchPanelInputClicked()

> **emitClearSearchPanelInputClicked**: () => `void`

Triggers an event indicating that the clear search panel input button has been clicked.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitClearSearchPanelInputClicked();```

***

### emitRegularExpressionToggled()

> **emitRegularExpressionToggled**: (`regularExpression`) => `void`

Triggers an event indicating that the search regular expression checkbox has been toggled.

#### Parameters

• **regularExpression**: `boolean`

`true` if regular expressions have been enabled, `false` otherwise.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitRegularExpressionToggled(true);```

***

### emitSearchResultClicked()

> **emitSearchResultClicked**: (`sr`) => `void`

Triggers an event indicating that a search result has been clicked.

#### Parameters

• **sr**: `any`

The search result that was clicked.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitSearchResultClicked(sr);```

***

### emitSettingsClicked()

> **emitSettingsClicked**: () => `void`

Triggers an event indicating that the search settings have been clicked.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitSettingsClicked();```

***

### emitToggled()

> **emitToggled**: (`active`) => `void`

Triggers an event indicating that the search panel has been toggled (opened or closed).

#### Parameters

• **active**: `boolean`

`true` if the search panel has been opened, `false` otherwise.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.emitToggled(true);```

***

### removeEventListener()

> **removeEventListener**: (`eventName`, `callback`) => `void`

Removes an event listener attached to a search event.

#### Parameters

• **eventName**: `"toggled"` \| `"searchResultClicked"` \| `"settingsClicked"` \| `"caseSensitiveToggled"` \| `"regularExpressionToggled"` \| `"clearSearchPanelInputClicked"`

The event name (e.g., `'toggled'`, `'searchResultClicked'`, etc.).

• **callback**: (`active`) => `void` \| (`searchResult`) => `void` \| () => `void` \| (`caseSensitive`) => `void` \| (`regularExpression`) => `void` \| () => `void`

The callback function to remove from the event listener.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.search.removeEventListener('toggled', callback);```

---

## Interface: StampAnnotations

# Interface: StampAnnotations

Groups all the API actions related to the stamp annotations.

## Properties

### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

#### Parameters

• **eventName**: `"toggled"` \| `"predefinedTextStampTypeSelected"`

• **callback**: (`active`) => `void` \| (`stampType`) => `void`

#### Returns

`void`

***

### emitPredefinedTextStampTypeSelected()

> **emitPredefinedTextStampTypeSelected**: (`stampType`) => `void`

Triggers an event indicating that a stamp type has been selected.

#### Parameters

• **stampType**: `PredefinedTextStampType`

The PredefinedTextStampType value that was selected.

#### Returns

`void`

***

### emitToggled()

> **emitToggled**: (`active`) => `void`

Triggers an event indicating that the stamp annotations panel has been toggled (opened or closed).

#### Parameters

• **active**: `boolean`

`true` if the stamp annotations panel has been opened, `false` otherwise.

#### Returns

`void`

#### Example

```PdfToolsViewerApi.stampAnnotations.emitToggled(true);```

***

### removeEventListener()

> **removeEventListener**: (`eventName`, `callback`) => `void`

#### Parameters

• **eventName**: `"toggled"` \| `"predefinedTextStampTypeSelected"`

• **callback**: (`active`) => `void` \| (`stampType`) => `void`

#### Returns

`void`

---

## Interface: StickyNotes

# Interface: StickyNotes

Groups all the API actions related to the sticky notes.

## Properties

### modals

> **modals**: `object`

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggled"`

• **callback**

##### Returns

`void`

#### cancelButton

> **cancelButton**: `object`

#### cancelButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### cancelButton.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### circleSelectColor

> **circleSelectColor**: `object`

#### circleSelectColor.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"selected"`

• **callback**

##### Returns

`void`

#### circleSelectColor.emitSelected()

> **emitSelected**: (`selected`, `color`) => `void`

##### Parameters

• **selected**: `boolean`

• **color**: \`#$\{string\}\`

##### Returns

`void`

#### emitToggled()

> **emitToggled**: (`options`) => `void`

##### Parameters

• **options**: `StickyNoteModalOptions`

##### Returns

`void`

#### lockButton

> **lockButton**: `object`

#### lockButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### lockButton.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### submitButton

> **submitButton**: `object`

#### submitButton.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### submitButton.emitClicked()

> **emitClicked**: (`options`) => `void`

##### Parameters

• **options**: `StickyNoteModalOptions`

##### Returns

`void`

---

## Interface: Toolbar

# Interface: Toolbar

Groups all the API actions related to the toolbar UI of the Viewer.

## toolbar

### button

> **button**: `object`

Groups all the API actions related to toolbar buttons.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to a toolbar button click event.

##### Parameters

• **eventName**: `"clicked"`

The event name to listen for (e.g., `'clicked'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.button.addEventListener('clicked', () => { console.log('callback') });```

#### emitClicked()

> **emitClicked**: (`componentName`, `payload`?) => `void`

Triggered when a toolbar button is clicked.

##### Parameters

• **componentName**: `string`

The name of the component (button) clicked.

• **payload?**: `unknown`

Optional payload with additional information the component needs.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.button.emitClicked('icon-button-print')```

#### hasEventListener()

> **hasEventListener**: (`eventName`) => `boolean`

Checks if an event listener is already attached to a toolbar button click event.

##### Parameters

• **eventName**: `"clicked"`

The event name to check (e.g., `'clicked'`).

##### Returns

`boolean`

`true` if the event listener is attached, otherwise `false`.

##### Example

```const hasEvent = PdfToolsViewerApi.toolbar.button.hasEventListener('clicked');```

#### overrideBehavior()

> **overrideBehavior**: (`viewerEl`, `buttonName`, `customBehavior`) => `void`

Overrides the default behavior of a button with a custom callback.

##### Parameters

• **viewerEl**: `PdfToolsViewer`

The Viewer DOM element.

• **buttonName**: `"pdftools-icon-button-save"`

The name of the button to override.

• **customBehavior**

A callback function defining the new behavior of the button.

##### Returns

`void`

***

### fitMode

> **fitMode**: `object`

Groups all the API actions related to the fit mode of the toolbar.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the fit mode update event.

##### Parameters

• **eventName**: `"updated"`

The event name to listen for (e.g., `'updated'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.fitMode.addEventListener('updated', () => { console.log('callback') });```

#### emitUpdated()

> **emitUpdated**: (`fitMode`) => `void`

Triggered when the fit mode is updated.

##### Parameters

• **fitMode**: [`FitMode`](../enumerations/FitMode.md)

The updated fit mode value.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.fitMode.emitUpdated(FitMode.FitWidth);```

***

### hamburgerMenu

> **hamburgerMenu**: `object`

Groups all the API actions related to the hamburger menu.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the hamburger menu visibility toggle event.

##### Parameters

• **eventName**: `"toggleVisibility"`

The event name to listen for (e.g., `'toggleVisibility'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.hamburgerMenu.addEventListener('toggleVisiblity', () => { console.log('callback') });```

#### emitToggleVisibility()

> **emitToggleVisibility**: (`visible`?) => `void`

Toggles the visibility of the hamburger menu.

##### Parameters

• **visible?**: `boolean`

Whether the menu should be visible (default is false).

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.hamburgerMenu.emitToggleVisibility(true);```

***

### pageMode

> **pageMode**: `object`

Groups all the API actions related to the page mode of the toolbar.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the page mode update event.

##### Parameters

• **eventName**: `"updated"`

The event name to listen for (e.g., `'updated'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.pageMode.addEventListener('updated', () => { console.log('callback') });```

#### emitUpdated()

> **emitUpdated**: (`pageMode`) => `void`

Triggered when the page mode is updated.

##### Parameters

• **pageMode**: [`PageLayoutMode`](../enumerations/PageLayoutMode.md)

The updated page mode value.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.pageMode.emitUpdated(PageLayoutMode.OneColumn);```

***

### thumbnails

> **thumbnails**: `object`

Groups all the API actions related to the thumbnails sidebar.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggleVisibility"`

• **callback**

##### Returns

`void`

#### emitToggleVisibility()

> **emitToggleVisibility**: (`visible`?) => `void`

##### Parameters

• **visible?**: `boolean`

##### Returns

`void`

#### Example

```PdfToolsViewerApi.toolbar.thumbnails.emitToggleVisibility(true);```
```PdfToolsViewerApi.toolbar.thumbnails.addEventListener('toggleVisibility', () => { console.log('callback') });```

***

### zoom

> **zoom**: `object`

Groups all the API actions related to the zoom functionality of the toolbar.

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

Adds an event listener to the zoom level update event.

##### Parameters

• **eventName**: `"updated"`

The event name to listen for (e.g., `'updated'`).

• **callback**

The callback function to execute when the event is triggered.

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.zoom.addEventListener('updated', () => { console.log('callback') });```

#### emitUpdated()

> **emitUpdated**: (`zoom`) => `void`

Triggered when the zoom level is updated.

##### Parameters

• **zoom**: `number`

The updated zoom value (between 0 and 1).

##### Returns

`void`

##### Example

```PdfToolsViewerApi.toolbar.zoom.emitUpdated(0.5);```

---

## Interface: Topbar

# Interface: Topbar

Groups all the API actions related to the topbar UI of the Viewer.

## Properties

### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

#### Parameters

• **eventName**: `"hideAll"`

• **callback**

#### Returns

`void`

***

### emitHideAll()

> **emitHideAll**: () => `void`

#### Returns

`void`

***

### highlightTopbar

> **highlightTopbar**: `object`

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggleVisibility"`

• **callback**

##### Returns

`void`

#### circleSelectColor

> **circleSelectColor**: `object`

#### circleSelectColor.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"selected"`

• **callback**

##### Returns

`void`

#### circleSelectColor.emitSelected()

> **emitSelected**: (`selected`, `color`) => `void`

##### Parameters

• **selected**: `boolean`

• **color**: \`#$\{string\}\`

##### Returns

`void`

#### drawHighlighter

> **drawHighlighter**: `object`

#### drawHighlighter.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### drawHighlighter.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### emitToggleVisibility()

> **emitToggleVisibility**: (`visible`?) => `void`

##### Parameters

• **visible?**: `boolean`

##### Returns

`void`

#### textAnnotationSquigglet

> **textAnnotationSquigglet**: `object`

#### textAnnotationSquigglet.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### textAnnotationSquigglet.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### textAnnotationStrikeout

> **textAnnotationStrikeout**: `object`

#### textAnnotationStrikeout.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### textAnnotationStrikeout.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

#### textAnnotationUnderline

> **textAnnotationUnderline**: `object`

#### textAnnotationUnderline.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"clicked"`

• **callback**

##### Returns

`void`

#### textAnnotationUnderline.emitClicked()

> **emitClicked**: () => `void`

##### Returns

`void`

***

### stickyNotesTopbar

> **stickyNotesTopbar**: `object`

#### addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"toggleVisibility"`

• **callback**

##### Returns

`void`

#### circleSelectColor

> **circleSelectColor**: `object`

#### circleSelectColor.addEventListener()

> **addEventListener**: (`eventName`, `callback`) => `void`

##### Parameters

• **eventName**: `"selected"`

• **callback**

##### Returns

`void`

#### circleSelectColor.emitSelected()

> **emitSelected**: (`selected`, `color`) => `void`

##### Parameters

• **selected**: `boolean`

• **color**: \`#$\{string\}\`

##### Returns

`void`

#### emitToggleVisibility()

> **emitToggleVisibility**: (`visible`?) => `void`

##### Parameters

• **visible?**: `boolean`

##### Returns

`void`

---

## Type Alias: HideableComponentConfigName

# Type Alias: HideableComponentConfigName

> **HideableComponentConfigName**: `"toolbar"` \| `"icon-button-hamburger"` \| `"icon-button-open"` \| `"icon-button-close"` \| `"icon-button-save"` \| `"icon-button-print"` \| `"toolbar-pagination"` \| `"icon-button-zoom-in"` \| `"icon-button-zoom-out"` \| `"dropdown-zoom"` \| `"dropdown-fitmode"` \| `"icon-button-rotate-left"` \| `"icon-button-rotate-right"` \| `"icon-button-thumbnails"` \| `"icon-button-outlines"` \| `"icon-button-annotations"` \| `"icon-button-search"` \| `"left-toolbar"`

---

## Class: LicenseError

# Class: LicenseError

## Extends

- `Error`

## Constructors

### new LicenseError()

> **new LicenseError**(`message`?): [`LicenseError`](LicenseError.md)

#### Parameters

• **message?**: `string`

#### Returns

[`LicenseError`](LicenseError.md)

#### Inherited from

`Error.constructor`

### new LicenseError()

> **new LicenseError**(`message`?, `options`?): [`LicenseError`](LicenseError.md)

#### Parameters

• **message?**: `string`

• **options?**: `ErrorOptions`

#### Returns

[`LicenseError`](LicenseError.md)

#### Inherited from

`Error.constructor`

## Properties

### cause?

> `optional` **cause**: `unknown`

#### Inherited from

`Error.cause`

***

### message

> **message**: `string`

#### Inherited from

`Error.message`

***

### name

> **name**: `string` = `'LicenseError'`

#### Overrides

`Error.name`

***

### stack?

> `optional` **stack**: `string`

#### Inherited from

`Error.stack`

---

## Enumeration: LicenseFeature

# 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

# @pdftools/pdf-web-sdk

## Namespaces

- [Core](namespaces/Core/index.md)
- [Pdf](namespaces/Pdf/index.md)
- [UI](namespaces/UI/index.md)

## Enumerations

- [LicenseFeature](enumerations/LicenseFeature.md)

## Classes

- [LicenseError](classes/LicenseError.md)

## Interfaces

- [PdfToolsWebSdkOptions](interfaces/PdfToolsWebSdkOptions.md)

## Type Aliases

- [LicenseKey](type-aliases/LicenseKey.md)

## Variables

- [pdfToolsWebSdk](variables/pdfToolsWebSdk.md)

---

## Interface: PdfToolsWebSdkOptions

# 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

***

### logLevel?

> `optional` **logLevel**: [`LogLevel`](../namespaces/Core/enumerations/LogLevel.md)

The log level used by the Pdftools PDF Web SDK

#### Default

```ts
LogLevel.ERROR
```

***

### logger?

> `optional` **logger**: `ILogger`

Logger class. Must implement ILogger

#### Default Value

`window.console`

***

### 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

```ts
'Pdftools'
```

---

## Class: EventEmitter\<T\>

# Class: EventEmitter\

EventEmitter is a class designed for managing and dispatching events.

## Extended by

- [`Page`](../../Pdf/classes/Page.md)
- [`Controller`](../../Pdf/classes/Controller.md)
- [`SearchExecution`](../../Pdf/namespaces/Search/classes/SearchExecution.md)
- [`Document`](../../Pdf/classes/Document.md)
- [`DocumentView`](../../UI/classes/DocumentView.md)
- [`Layer`](../../UI/classes/Layer.md)
- [`TextSelectionPlugin`](../../UI/classes/TextSelectionPlugin.md)

## Type Parameters

• **T** *extends* `Record`\ `void`\>

Interface which describes the event names and their associated callback types.

## Constructors

### new EventEmitter()

> **new EventEmitter**\(): [`EventEmitter`](EventEmitter.md)\

#### Returns

[`EventEmitter`](EventEmitter.md)\

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

---

## Enumeration: LogLevel

# 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()

# Function: delay()

> **delay**(`seconds`): `Promise`\

## Parameters

• **seconds**: `number`

## Returns

`Promise`\

---

## Core

# Core

## Index

### Enumerations

- [LogLevel](enumerations/LogLevel.md)

### Classes

- [EventEmitter](classes/EventEmitter.md)

### Interfaces

- [Cloneable](interfaces/Cloneable.md)
- [Disposable](interfaces/Disposable.md)

### Type Aliases

- [Brand](type-aliases/Brand.md)

### Variables

- [logger](variables/logger.md)

### Functions

- [delay](functions/delay.md)

---

## Interface: Cloneable\<T\>

# Interface: Cloneable\

Represents an object that can be cloned to create a deep copy.

## Type Parameters

• **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

# 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`

---

## Type Alias: Brand\<T, U\>

# Type Alias: Brand\

> **Brand**\: `T` & `object`

Makes a branded type synonym
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**

• **U**

---

## Variable: logger

# Variable: logger

> `const` **logger**: `Logger`

Singleton instance of the Logger class.

---

## Class: AnnotationManager

# Class: AnnotationManager

Class for all annotation related operations.

## Constructors

### new AnnotationManager()

> **new AnnotationManager**(`document`): [`AnnotationManager`](AnnotationManager.md)

#### Parameters

• **document**: [`Document`](Document.md)

#### Returns

[`AnnotationManager`](AnnotationManager.md)

## Methods

### add()

#### add(annotation)

> **add**(`annotation`): `Promise`\

Adds a single annotation to the document.

##### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to be added.

##### Returns

`Promise`\

#### add(annotations)

> **add**(`annotations`): `Promise`\

Adds multiple annotations to the document.

##### Parameters

• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]

An array of annotations to be added.

##### Returns

`Promise`\

***

### bringToBack()

> **bringToBack**(`annotation`): `void`

**`Experimental`**

Brings the specified annotation to the back, making it appear below other annotations.

#### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to bring to the back.

#### Returns

`void`

***

### bringToFront()

> **bringToFront**(`annotation`): `void`

**`Experimental`**

Brings the specified annotation to the front, making it appear above other annotations.

#### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to bring to the front.

#### Returns

`void`

***

### copy()

> **copy**(`annotation`): `void`

**`Experimental`**

Creates a copy of the specified annotation.

#### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to be copied.

#### Returns

`void`

***

### delete()

#### delete(annotation)

> **delete**(`annotation`): `Promise`\

Deletes a single annotation from the document.

##### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to be deleted.

##### Returns

`Promise`\

#### delete(annotations)

> **delete**(`annotations`): `Promise`\

Deletes multiple annotations from the document.

##### Parameters

• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]

An array of annotations to be deleted.

##### Returns

`Promise`\

#### delete(annotationId)

> **delete**(`annotationId`): `Promise`\

**`Experimental`**

Deletes an annotation by its ID from the document.

##### Parameters

• **annotationId**: `string`

The ID of the annotation to be deleted.

##### Returns

`Promise`\

***

### getAll()

> **getAll**(): `Promise`\

Retrieves a list of all annotations in the document.

#### Returns

`Promise`\

An array containing all the annotations.

***

### getAllOnPage()

> **getAllOnPage**(`pageNumber`): `Promise`\

Retrieves annotations on a specific page.

#### Parameters

• **pageNumber**: `number`

The page number to retrieve annotations from.

#### Returns

`Promise`\

An array containing all the annotations on a specific page.

***

### getAnnotationsOnPoint()

> **getAnnotationsOnPoint**(`pageNumber`, `point`, `onlySelectable`): `Promise`\

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`\

An array containing all the annotations on point.

***

### getById()

> **getById**(`annotationId`): [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

**`Experimental`**

Retrieves an annotation by its ID from the document.

#### Parameters

• **annotationId**: `string`

The ID of the annotation to retrieve.

#### Returns

[`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The retrieved annotation.

***

### getTextStampAspectRatio()

> **getTextStampAspectRatio**(`text`): `Promise`\

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`\

A promise that resolves to the aspect ratio (width divided by height) of the custom text stamp.

***

### hide()

#### hide(annotation)

> **hide**(`annotation`): `Promise`\

Hides the specified annotation, making it invisible within the document.

##### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to be hidden.

##### Returns

`Promise`\

#### hide(annotations)

> **hide**(`annotations`): `Promise`\

**`Experimental`**

Hides multiple annotations, making them invisible within the document.

##### Parameters

• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]

An array of annotations to be hidden.

##### Returns

`Promise`\

***

### update()

#### update(annotation)

> **update**(`annotation`): `Promise`\

Updates a single annotation in the document.

##### Parameters

• **annotation**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)

The annotation to be updated.

##### Returns

`Promise`\

#### update(annotations)

> **update**(`annotations`): `Promise`\

Updates multiple annotations in the document.

##### Parameters

• **annotations**: [`Annotation`](../namespaces/Annotations/classes/Annotation.md)[]

An array of annotations to be updated.

##### Returns

`Promise`\

---

## Class: Controller

# Class: Controller

Class used for managing PDF documents.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Implements

- [`Disposable`](../../Core/interfaces/Disposable.md)

## Constructors

### new Controller()

> **new Controller**(`controllerOptions`): [`Controller`](Controller.md)

#### Parameters

• **controllerOptions**: `ControllerOptions` = `{}`

#### Returns

[`Controller`](Controller.md)

#### Overrides

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#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.

#### Returns

`void`

#### Implementation of

[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)

***

### initialize()

> **initialize**(): `Promise`\

#### Returns

`Promise`\

***

### isFeatureEnabled()

> **isFeatureEnabled**(`featureId`): `boolean`

#### Parameters

• **featureId**: [`LicensedFeatureId`](../enumerations/LicensedFeatureId.md)

#### Returns

`boolean`

***

### openDocument()

> **openDocument**(`inputDocument`): `Promise`\

Opens a PDF document from either a file or a remote URI.

#### Parameters

• **inputDocument**: [`InputFile`](../interfaces/InputFile.md) \| [`InputUri`](../interfaces/InputUri.md)

The input document to open.

#### Returns

`Promise`\

A Promise that resolves to a `Pdf.Document`.

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

---

## Class: Document

# Class: Document

Represents a Pdf document.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Implements

- [`Disposable`](../../Core/interfaces/Disposable.md)

## Accessors

### annotations

> `get` **annotations**(): [`AnnotationManager`](AnnotationManager.md)

#### Returns

[`AnnotationManager`](AnnotationManager.md)

***

### controller

> `get` **controller**(): [`Controller`](Controller.md)

Gets the `Pdf.Controller`

#### Returns

[`Controller`](Controller.md)

***

### forms

> `get` **forms**(): []

#### Returns

[]

***

### hasChanges

> `get` **hasChanges**(): `boolean`

indicates if the document has been changed since the document
was opened or last saved

#### Returns

`boolean`

***

### pageCount

> `get` **pageCount**(): `number`

#### Returns

`number`

***

### pages

> `get` **pages**(): [`PageList`](PageList.md)

#### Returns

[`PageList`](PageList.md)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#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.

#### Returns

`void`

#### Implementation of

[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)

***

### getMetadata()

> **getMetadata**(): `Promise`\

#### Returns

`Promise`\

***

### loadTextFragments()

> **loadTextFragments**(): `Promise`\

Loads text fragments of a `Pdf.Document`.

#### Returns

`Promise`\

A Promise that resolves to an Array containing the text fragments.

***

### registerImage()

> **registerImage**(`image`): `Promise`\

Register the image in the PDF document so it can be reused.

#### Parameters

• **image**: `Uint8Array`

I

#### Returns

`Promise`\

***

### registerPdfContent()

> **registerPdfContent**(`page`): `Promise`\

Register the PDF page in the PDF document so it can be reused.

#### Parameters

• **page**: [`Page`](Page.md)

#### Returns

`Promise`\

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

***

### renderPage()

> **renderPage**(`pageNumber`, `width`, `height`): `Promise`\

#### Parameters

• **pageNumber**: `number`

• **width**: `number`

• **height**: `number`

#### Returns

`Promise`\

***

### save()

> **save**(`options`): `Promise`\

Saves the changes made to the `Pdf.Document`.

#### Parameters

• **options**: [`DocumentSaveOptions`](../interfaces/DocumentSaveOptions.md) = `defaultDocumentSaveOptions`

Options for configuring the document save behavior.

#### Returns

`Promise`\

A Promise that resolves to a Blob containing the updated PDF document.

---

## Class: FileNotFoundError

# Class: FileNotFoundError

## Extends

- `Error`

## Constructors

### new FileNotFoundError()

> **new FileNotFoundError**(`message`?): [`FileNotFoundError`](FileNotFoundError.md)

#### Parameters

• **message?**: `string`

#### Returns

[`FileNotFoundError`](FileNotFoundError.md)

#### Inherited from

`Error.constructor`

### new FileNotFoundError()

> **new FileNotFoundError**(`message`?, `options`?): [`FileNotFoundError`](FileNotFoundError.md)

#### Parameters

• **message?**: `string`

• **options?**: `ErrorOptions`

#### Returns

[`FileNotFoundError`](FileNotFoundError.md)

#### 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

# Class: InvalidPasswordError

## Extends

- `Error`

## Constructors

### new InvalidPasswordError()

> **new InvalidPasswordError**(`message`?): [`InvalidPasswordError`](InvalidPasswordError.md)

#### Parameters

• **message?**: `string`

#### Returns

[`InvalidPasswordError`](InvalidPasswordError.md)

#### Inherited from

`Error.constructor`

### new InvalidPasswordError()

> **new InvalidPasswordError**(`message`?, `options`?): [`InvalidPasswordError`](InvalidPasswordError.md)

#### Parameters

• **message?**: `string`

• **options?**: `ErrorOptions`

#### Returns

[`InvalidPasswordError`](InvalidPasswordError.md)

#### 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

# Class: Metadata

Document metadata according to the PDF standard (PDF 1.7)

## Constructors

### new Metadata()

> **new Metadata**(): [`Metadata`](Metadata.md)

#### Returns

[`Metadata`](Metadata.md)

## 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

# Class: NotLoadedError

## Extends

- `Error`

## Constructors

### new NotLoadedError()

> **new NotLoadedError**(`message`?): [`NotLoadedError`](NotLoadedError.md)

#### Parameters

• **message?**: `string`

#### Returns

[`NotLoadedError`](NotLoadedError.md)

#### Inherited from

`Error.constructor`

### new NotLoadedError()

> **new NotLoadedError**(`message`?, `options`?): [`NotLoadedError`](NotLoadedError.md)

#### Parameters

• **message?**: `string`

• **options?**: `ErrorOptions`

#### Returns

[`NotLoadedError`](NotLoadedError.md)

#### 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

# Class: Page

A single page in a Pdf document.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Accessors

### document

> `get` **document**(): [`Document`](Document.md)

the pdf document to which the page belongs

#### Returns

[`Document`](Document.md)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

indicates if the page or its content has been changed since the document
was last saved

#### Returns

`boolean`

***

### height

> `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` **isDeleted**(): `boolean`

indicates whether the page was deleted

#### Returns

`boolean`

***

### originalHeight

> `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` **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` **pageNumber**(): `number`

page number

#### Returns

`number`

***

### rotation

> `get` **rotation**(): [`Rotation`](../enumerations/Rotation.md)

Rotation of the page

#### Returns

[`Rotation`](../enumerations/Rotation.md)

***

### width

> `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**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)

***

### getTextFragments()

> **getTextFragments**(): [`TextFragment`](../interfaces/TextFragment.md)[]

Gets text fragments of a `Pdf.Page`.

#### Returns

[`TextFragment`](../interfaces/TextFragment.md)[]

A Promise that resolves to an Array containing the text fragments.

#### Throws

`Pdf.NotLoadedError` if text fragments are not loaded yet.

***

### loadTextFragments()

> **loadTextFragments**(): `Promise`\

Loads text fragments of a `Pdf.Page`.

#### Returns

`Promise`\

A Promise that resolves to an Array containing the text fragments.

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

***

### render()

> **render**(`renderOptions`): `Promise`\

Render the given page

#### Parameters

• **renderOptions**: [`PageRenderOptions`](PageRenderOptions.md)

#### Returns

`Promise`\

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`](../enumerations/RotationDirection.md)

clockwise or counter-clockwise

• **degree**: `number` = `90`

rotation in degrees in multiples of 90

#### Returns

`void`

***

### transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral()

> **transformDocumentViewPointQuadrilateralToPdfPointQuadrilateral**(`quadrilateral`, `width`, `height`, `rotation`): [`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\

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`](../namespaces/Geometry/classes/Quadrilateral.md)\

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`](../enumerations/Rotation.md)

The rotation of the page.

#### Returns

[`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\

A new instance of `Quadrilateral` representing the converted coordinates in PDF units.

***

### transformDocumentViewPointRectangleToPdfPointRectangle()

> **transformDocumentViewPointRectangleToPdfPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../enumerations/Rotation.md)

The rotation of the page.

#### Returns

[`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../enumerations/Rotation.md)

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`](../namespaces/Geometry/classes/Quadrilateral.md)\

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`](../namespaces/Geometry/classes/Quadrilateral.md)\

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`](../enumerations/Rotation.md)

The rotation of the page.

#### Returns

[`Quadrilateral`](../namespaces/Geometry/classes/Quadrilateral.md)\

A new instance of `Quadrilateral` representing the converted coordinates in document view units.

***

### transformPdfPointRectangleToDocumentViewPointRectangle()

> **transformPdfPointRectangleToDocumentViewPointRectangle**(`rectangle`, `width`, `height`, `rotation`): [`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../enumerations/Rotation.md)

The rotation of the page.

#### Returns

[`Rectangle`](../namespaces/Geometry/classes/Rectangle.md)\

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`](../enumerations/Rotation.md)

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`](../enumerations/Rotation.md)

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`](../enumerations/Rotation.md)

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: PageList

Class for all page-related operations in a PDF document.

## Methods

### add()

#### add(page, index)

> **add**(`page`, `index`?): `Promise`\

**`Experimental`**

Adds a page to the document.

##### Parameters

• **page**: [`Page`](Page.md)

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`\

#### add(pages, index)

> **add**(`pages`, `index`?): `Promise`\

**`Experimental`**

Adds multiple pages to the document.

##### Parameters

• **pages**: [`Page`](Page.md)[]

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`\

***

### delete()

#### delete(page)

> **delete**(`page`): `Promise`\

**`Experimental`**

Deletes a single page from the document.

##### Parameters

• **page**: [`Page`](Page.md)

##### Returns

`Promise`\

#### delete(pages)

> **delete**(`pages`): `Promise`\

**`Experimental`**

Deletes multiple pages from the document.

##### Parameters

• **pages**: [`Page`](Page.md)[]

##### Returns

`Promise`\

***

### getAll()

> **getAll**(): [`Page`](Page.md)[]

Get an array with all pages in the document.

#### Returns

[`Page`](Page.md)[]

An array of Page objects representing all pages in the document.

***

### getByIndex()

> **getByIndex**(`pageIndex`): [`Page`](Page.md)

Get a page by index.

#### Parameters

• **pageIndex**: `number`

The index of the page to retrieve.

#### Returns

[`Page`](Page.md)

The Page object at the specified index.

***

### getByNumber()

> **getByNumber**(`pageNumber`): [`Page`](Page.md)

Get a page by its page number.

#### Parameters

• **pageNumber**: `number`

The page number to search for.

#### Returns

[`Page`](Page.md)

The Page object with the specified page number, or undefined if not found.

***

### rotate()

#### rotate(page, options)

> **rotate**(`page`, `options`?): `Promise`\

**`Experimental`**

Rotates a single page.

##### Parameters

• **page**: [`Page`](Page.md)

Page to be rotated.

• **options?**

Optional parameters for specifying the rotation angle.

• **options.absoluteRotation?**: `number`

• **options.rotation?**: `number`

##### Returns

`Promise`\

#### rotate(pages, options)

> **rotate**(`pages`, `options`?): `Promise`\

**`Experimental`**

Rotates multiple pages.

##### Parameters

• **pages**: [`Page`](Page.md)[]

An array of pages to be rotated.

• **options?**

Optional parameters for specifying the rotation angle.

• **options.absoluteRotation?**: `number`

• **options.rotation?**: `number`

##### Returns

`Promise`\

---

## Class: PageRenderOptions

# Class: PageRenderOptions

**`Experimental`**

## Constructors

### new PageRenderOptions()

> **new PageRenderOptions**(): [`PageRenderOptions`](PageRenderOptions.md)

**`Experimental`**

#### Returns

[`PageRenderOptions`](PageRenderOptions.md)

## Properties

### noPrint

> **noPrint**: `boolean`

**`Experimental`**

## Accessors

### annotationFilter

> `set` **annotationFilter**(`filter`): `void`

**`Experimental`**

#### Parameters

• **filter**

---

## Enumeration: FitMode

# 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: LicensedFeatureId

# 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: PageLayoutMode

# 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: Rotation

# 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: RotationDirection

# Enumeration: RotationDirection

## Enumeration Members

### clockwise

> **clockwise**: `0`

***

### counterClockwise

> **counterClockwise**: `1`

---

## Pdf

# Pdf

## Index

### Namespaces

- [Actions](namespaces/Actions/index.md)
- [Annotations](namespaces/Annotations/index.md)
- [Destination](namespaces/Destination/index.md)
- [Drawing](namespaces/Drawing/index.md)
- [Forms](namespaces/Forms/index.md)
- [Geometry](namespaces/Geometry/index.md)
- [Search](namespaces/Search/index.md)

### Enumerations

- [FitMode](enumerations/FitMode.md)
- [LicensedFeatureId](enumerations/LicensedFeatureId.md)
- [PageLayoutMode](enumerations/PageLayoutMode.md)
- [Rotation](enumerations/Rotation.md)
- [RotationDirection](enumerations/RotationDirection.md)

### Classes

- [AnnotationManager](classes/AnnotationManager.md)
- [Controller](classes/Controller.md)
- [Document](classes/Document.md)
- [FileNotFoundError](classes/FileNotFoundError.md)
- [InvalidPasswordError](classes/InvalidPasswordError.md)
- [Metadata](classes/Metadata.md)
- [NotLoadedError](classes/NotLoadedError.md)
- [Page](classes/Page.md)
- [PageList](classes/PageList.md)
- [PageRenderOptions](classes/PageRenderOptions.md)

### Interfaces

- [ControllerEventMap](interfaces/ControllerEventMap.md)
- [DocumentEventMap](interfaces/DocumentEventMap.md)
- [DocumentSaveOptions](interfaces/DocumentSaveOptions.md)
- [HttpOptions](interfaces/HttpOptions.md)
- [InputDocument](interfaces/InputDocument.md)
- [InputFile](interfaces/InputFile.md)
- [InputUri](interfaces/InputUri.md)
- [PageEventMap](interfaces/PageEventMap.md)
- [PdfImage](interfaces/PdfImage.md)
- [SaveOptions](interfaces/SaveOptions.md)
- [TextFragment](interfaces/TextFragment.md)

---

## Interface: ControllerEventMap

# 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: DocumentEventMap

# Interface: DocumentEventMap

Interface defining event types for `Pdf.Document`.

---

## Interface: DocumentSaveOptions

# Interface: DocumentSaveOptions

Options for configuring the document save behavior.

## Properties

### 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

```ts
false
```

---

## Interface: HttpOptions

# 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

# Interface: InputDocument

## Extended by

- [`InputFile`](InputFile.md)
- [`InputUri`](InputUri.md)

## 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

```ts
false
```

***

### fileName?

> `optional` **fileName**: `string`

Name for the input document

***

### password?

> `optional` **password**: `string`

The password used for opening the PdfDocument.

---

## Interface: InputFile

# Interface: InputFile

A file that can be opened on a `Blob`, `File` or `Uint8Array`.

## Extends

- [`InputDocument`](InputDocument.md)

## Properties

### annotationTag?

> `optional` **annotationTag**: `string`

Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF).

#### Inherited from

[`InputDocument`](InputDocument.md).[`annotationTag`](InputDocument.md#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

```ts
false
```

#### Inherited from

[`InputDocument`](InputDocument.md).[`autoRepairDisabled`](InputDocument.md#autorepairdisabled)

***

### data

> **data**: `Uint8Array` \| `Blob` \| `File`

A `Blob`, `File` or `Uint8Array` containing the file.

***

### fileName?

> `optional` **fileName**: `string`

Name for the input document

#### Inherited from

[`InputDocument`](InputDocument.md).[`fileName`](InputDocument.md#filename)

***

### password?

> `optional` **password**: `string`

The password used for opening the PdfDocument.

#### Inherited from

[`InputDocument`](InputDocument.md).[`password`](InputDocument.md#password)

---

## Interface: InputUri

# Interface: InputUri

A file that can be opened on a text-uri.

## Extends

- [`InputDocument`](InputDocument.md)

## Properties

### annotationTag?

> `optional` **annotationTag**: `string`

Tag that helps grouping annotations coming from present document (PDF, FDF or XFDF).

#### Inherited from

[`InputDocument`](InputDocument.md).[`annotationTag`](InputDocument.md#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

```ts
false
```

#### Inherited from

[`InputDocument`](InputDocument.md).[`autoRepairDisabled`](InputDocument.md#autorepairdisabled)

***

### fileName?

> `optional` **fileName**: `string`

Name for the input document

#### Inherited from

[`InputDocument`](InputDocument.md).[`fileName`](InputDocument.md#filename)

***

### httpOptions?

> `optional` **httpOptions**: [`HttpOptions`](HttpOptions.md)

Options that are applied to a HTTP request.

***

### password?

> `optional` **password**: `string`

The password used for opening the PdfDocument.

#### Inherited from

[`InputDocument`](InputDocument.md).[`password`](InputDocument.md#password)

***

### uri

> **uri**: `string`

The uri where the file can be loaded from.

---

## Interface: PageEventMap

# 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`](TextFragment.md)[]

#### Returns

`void`

---

## Interface: PdfImage

# Interface: PdfImage

An interface representing an image which is registered in a PDF document and can be reused.

## Properties

### id

> **id**: `number`

---

## Interface: SaveOptions

# Interface: SaveOptions

Options used for saving [Pdf.Document](../classes/Document.md)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`](../namespaces/Annotations/classes/Annotation.md)

#### 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

# 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`](../namespaces/Geometry/classes/Quadrilateral.md)\

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.

---

## Class: `abstract` Action

# Class: `abstract` 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`](GoToAction.md)
- [`RemoteGoToAction`](RemoteGoToAction.md)
- [`ResetFormAction`](ResetFormAction.md)
- [`SubmitFormAction`](SubmitFormAction.md)
- [`UriAction`](UriAction.md)

## Constructors

### new Action()

> **new Action**(): [`Action`](Action.md)

**`Experimental`**

#### Returns

[`Action`](Action.md)

---

## Class: GoToAction

# Class: GoToAction

**`Experimental`**

GoToAction

Go to a specific point in the document.

## Extends

- [`Action`](Action.md)

## Constructors

### new GoToAction()

> **new GoToAction**(): [`GoToAction`](GoToAction.md)

**`Experimental`**

#### Returns

[`GoToAction`](GoToAction.md)

#### Inherited from

[`Action`](Action.md).[`constructor`](Action.md#constructors)

---

## Class: RemoteGoToAction

# Class: RemoteGoToAction

**`Experimental`**

RemoteGoToAction

Go to some remote location outside the current document.

## Extends

- [`Action`](Action.md)

## Constructors

### new RemoteGoToAction()

> **new RemoteGoToAction**(): [`RemoteGoToAction`](RemoteGoToAction.md)

**`Experimental`**

#### Returns

[`RemoteGoToAction`](RemoteGoToAction.md)

#### Inherited from

[`Action`](Action.md).[`constructor`](Action.md#constructors)

---

## Class: ResetFormAction

# Class: ResetFormAction

**`Experimental`**

ResetFormAction

Reset the current form.

## Extends

- [`Action`](Action.md)

## Constructors

### new ResetFormAction()

> **new ResetFormAction**(): [`ResetFormAction`](ResetFormAction.md)

**`Experimental`**

#### Returns

[`ResetFormAction`](ResetFormAction.md)

#### Inherited from

[`Action`](Action.md).[`constructor`](Action.md#constructors)

---

## Class: SubmitFormAction

# Class: SubmitFormAction

**`Experimental`**

SubmitFormAction

Submit the current form.

## Extends

- [`Action`](Action.md)

## Constructors

### new SubmitFormAction()

> **new SubmitFormAction**(): [`SubmitFormAction`](SubmitFormAction.md)

**`Experimental`**

#### Returns

[`SubmitFormAction`](SubmitFormAction.md)

#### Inherited from

[`Action`](Action.md).[`constructor`](Action.md#constructors)

---

## Class: UriAction

# Class: UriAction

**`Experimental`**

UriAction

Go to a specified URI.

## Extends

- [`Action`](Action.md)

## Constructors

### new UriAction()

> **new UriAction**(`uri`): [`UriAction`](UriAction.md)

**`Experimental`**

#### Parameters

• **uri**: `string`

#### Returns

[`UriAction`](UriAction.md)

#### Overrides

[`Action`](Action.md).[`constructor`](Action.md#constructors)

## Properties

### uri

> **uri**: `string`

**`Experimental`**

---

## Actions

# Actions

## Index

### Classes

- [Action](classes/Action.md)
- [GoToAction](classes/GoToAction.md)
- [RemoteGoToAction](classes/RemoteGoToAction.md)
- [ResetFormAction](classes/ResetFormAction.md)
- [SubmitFormAction](classes/SubmitFormAction.md)
- [UriAction](classes/UriAction.md)

---

## Class: `abstract` Annotation

# Class: `abstract` Annotation

Base class for all annotations.

## Extended by

- [`LinkAnnotation`](LinkAnnotation.md)
- [`MarkupAnnotation`](MarkupAnnotation.md)
- [`WatermarkAnnotation`](WatermarkAnnotation.md)
- [`WidgetAnnotation`](WidgetAnnotation.md)

## Constructors

### new Annotation()

> **new Annotation**(`options`): [`Annotation`](Annotation.md)

Creates a new `Annotation` instance.

#### Parameters

• **options**: [`AnnotationOptions`](../interfaces/AnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`Annotation`](Annotation.md)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

> `set` **\_\_annotation**(`v`): `void`

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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.

> `set` **boundingBox**(`rectangle`): `void`

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

***

### content

> `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.

> `set` **content**(`content`): `void`

#### Parameters

• **content**: `string`

#### Returns

`string`

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

#### Parameters

• **date**: `Date`

#### Returns

`Date`

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

***

### hidden

> `get` **hidden**(): `boolean`

If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.

> `set` **hidden**(`hidden`): `void`

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

***

### interactive

> `get` **interactive**(): `boolean`

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

***

### isMaintainingAspectRatio

> `get` `abstract` **isMaintainingAspectRatio**(): `boolean`

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

***

### isMarkupAnnotation

> `get` `abstract` **isMarkupAnnotation**(): `boolean`

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

***

### isMoveable

> `get` `abstract` **isMoveable**(): `boolean`

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

***

### isResizable

> `get` `abstract` **isResizable**(): `boolean`

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

***

### isRotatable

> `get` `abstract` **isRotatable**(): `boolean`

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

***

### isSelectable

> `get` `abstract` **isSelectable**(): `boolean`

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

***

### isWidgetAnnotation

> `get` `abstract` **isWidgetAnnotation**(): `boolean`

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

#### Parameters

• **privateData**: `object`

#### Returns

`object`

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.

> `set` **renderProperties**(`v`): `void`

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

***

### source

> `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`.

#### Returns

`void`

***

### type

> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

---

## Class: AnnotationRenderProperties

# Class: AnnotationRenderProperties

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

## Constructors

### new AnnotationRenderProperties()

> **new AnnotationRenderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

## Accessors

### fixedRotation

> `get` **fixedRotation**(): `boolean`

Specifies whether the annotation's appearance should remain fixed in orientation when the page is rotated.

> `set` **fixedRotation**(`fixedRotation`): `void`

#### Parameters

• **fixedRotation**: `boolean`

#### Returns

`boolean`

***

### fixedZoom

> `get` **fixedZoom**(): `boolean`

Indicates whether the annotation's appearance should remain fixed in scale when the page's magnification level is changed.

> `set` **fixedZoom**(`fixedZoom`): `void`

#### Parameters

• **fixedZoom**: `boolean`

#### Returns

`boolean`

***

### renderToPrint

> `get` **renderToPrint**(): `boolean`

Specifies whether the annotation should be printed when the page is printed, regardless of its visibility on the screen.

> `set` **renderToPrint**(`renderToPrint`): `void`

#### Parameters

• **renderToPrint**: `boolean`

#### Returns

`boolean`

***

### renderToScreen

> `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.

> `set` **renderToScreen**(`renderToScreen`): `void`

#### Parameters

• **renderToScreen**: `boolean`

#### Returns

`boolean`

---

## Class: CaretAnnotation

# Class: CaretAnnotation

**`Experimental`**

An annotation that marks a point to insert text

## Extends

- [`MarkupAnnotation`](MarkupAnnotation.md)

## Constructors

### new CaretAnnotation()

> **new CaretAnnotation**(`options`): [`CaretAnnotation`](CaretAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`CaretAnnotationOptions`](../interfaces/CaretAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`CaretAnnotation`](CaretAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Caret`

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

---

## Class: `abstract` DrawingAnnotation

# Class: `abstract` DrawingAnnotation

**`Experimental`**

Base class for drawing annotations

## Extends

- [`MarkupAnnotation`](MarkupAnnotation.md)

## Extended by

- [`InkAnnotation`](InkAnnotation.md)
- [`LineAnnotation`](LineAnnotation.md)
- [`PolyLineAnnotation`](PolyLineAnnotation.md)
- [`ShapeAnnotation`](ShapeAnnotation.md)

## Constructors

### new DrawingAnnotation()

> **new DrawingAnnotation**(`options`): [`DrawingAnnotation`](DrawingAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`DrawingAnnotationOptions`](../interfaces/DrawingAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`DrawingAnnotation`](DrawingAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### type

> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

---

## Class: EllipseAnnotation

# Class: EllipseAnnotation

**`Experimental`**

An ellipse drawing annotation

## Extends

- [`ShapeAnnotation`](ShapeAnnotation.md)

## Constructors

### new EllipseAnnotation()

> **new EllipseAnnotation**(`options`): [`EllipseAnnotation`](EllipseAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`EllipseAnnotationOptions`](../interfaces/EllipseAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`EllipseAnnotation`](EllipseAnnotation.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateCreated`](ShapeAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)

---

## Class: `abstract` FileAttachmentAnnotation

# Class: `abstract` 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`](MarkupAnnotation.md)

## Constructors

### new FileAttachmentAnnotation()

> **new FileAttachmentAnnotation**(`options`): [`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`FileAttachmentAnnotationOptions`](../interfaces/FileAttachmentAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Properties

### icon

> **icon**: [`FileAttachmentAnnotationIcon`](../enumerations/FileAttachmentAnnotationIcon.md)

**`Experimental`**

The icon to be used in displaying the annotation.

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

---

## Class: FreeTextAnnotation

# 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`](MarkupAnnotation.md)

## Constructors

### new FreeTextAnnotation()

> **new FreeTextAnnotation**(`options`): [`FreeTextAnnotation`](FreeTextAnnotation.md)

Creates a new `FreeTextAnnotation` instance.

#### Parameters

• **options**: [`FreeTextAnnotationOptions`](../interfaces/FreeTextAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`FreeTextAnnotation`](FreeTextAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `FreeTextAnnotation`

> `set` **\_\_annotation**(`v`): `void`

#### Parameters

• **v**: `FreeTextAnnotation`

#### Returns

`FreeTextAnnotation`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

The author.

> `set` **author**(`author`): `void`

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### backgroundColor

> `get` **backgroundColor**(): `string`

Background color for the annotation.

> `set` **backgroundColor**(`color`): `void`

#### Parameters

• **color**: `string`

#### Returns

`string`

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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.

> `set` **boundingBox**(`rectangle`): `void`

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `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`

#### Returns

`string`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `get` **hidden**(): `boolean`

If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.

> `set` **hidden**(`hidden`): `void`

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.

> `set` **renderProperties**(`v`): `void`

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### richText

> `get` **richText**(): `string`

A rich text string that shall be displayed in the popup window when the
annotation is opened.

> `set` **richText**(`richText`): `void`

#### Parameters

• **richText**: `string`

#### Returns

`string`

***

### rotation

> `get` **rotation**(): [`Rotation`](../../../enumerations/Rotation.md)

Rotation of the annotation

> `set` **rotation**(`rotation`): `void`

#### Parameters

• **rotation**: [`Rotation`](../../../enumerations/Rotation.md)

#### Returns

[`Rotation`](../../../enumerations/Rotation.md)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

The subject.

> `set` **subject**(`subject`): `void`

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

---

## Class: InkAnnotation

# Class: InkAnnotation

**`Experimental`**

A free-hand drawing annotation

## Extends

- [`DrawingAnnotation`](DrawingAnnotation.md)

## Constructors

### new InkAnnotation()

> **new InkAnnotation**(`options`): [`InkAnnotation`](InkAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`InkAnnotationOptions`](../interfaces/InkAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`InkAnnotation`](InkAnnotation.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateCreated`](DrawingAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)

---

## Class: LineAnnotation

# Class: LineAnnotation

**`Experimental`**

A line annotation

## Extends

- [`DrawingAnnotation`](DrawingAnnotation.md)

## Constructors

### new LineAnnotation()

> **new LineAnnotation**(`options`): [`LineAnnotation`](LineAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`LineAnnotationOptions`](../interfaces/LineAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`LineAnnotation`](LineAnnotation.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateCreated`](DrawingAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)

---

## Class: LinkAnnotation

# Class: LinkAnnotation

**`Experimental`**

A link annotation

## Extends

- [`Annotation`](Annotation.md)

## Constructors

### new LinkAnnotation()

> **new LinkAnnotation**(`options`): [`LinkAnnotation`](LinkAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`LinkAnnotationOptions`](../interfaces/LinkAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`LinkAnnotation`](LinkAnnotation.md)

#### Overrides

[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the link annotation is clicked on

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`Annotation`](Annotation.md).[`content`](Annotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`id`](Annotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`Annotation`](Annotation.md).[`page`](Annotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`source`](Annotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Link`

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`Annotation`](Annotation.md).[`type`](Annotation.md#type)

---

## Class: `abstract` MarkupAnnotation

# Class: `abstract` MarkupAnnotation

Base class for all markup annotations

## Extends

- [`Annotation`](Annotation.md)

## Extended by

- [`CaretAnnotation`](CaretAnnotation.md)
- [`DrawingAnnotation`](DrawingAnnotation.md)
- [`FileAttachmentAnnotation`](FileAttachmentAnnotation.md)
- [`FreeTextAnnotation`](FreeTextAnnotation.md)
- [`NoteAnnotation`](NoteAnnotation.md)
- [`StampAnnotation`](StampAnnotation.md)
- [`TextMarkupAnnotation`](TextMarkupAnnotation.md)

## Constructors

### new MarkupAnnotation()

> **new MarkupAnnotation**(`options`): [`MarkupAnnotation`](MarkupAnnotation.md)

#### Parameters

• **options**: [`MarkupAnnotationOptions`](../interfaces/MarkupAnnotationOptions.md)

#### Returns

[`MarkupAnnotation`](MarkupAnnotation.md)

#### Overrides

[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

> `set` **\_\_annotation**(`v`): `void`

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Overrides

[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)

***

### author

> `get` **author**(): `string`

The author.

> `set` **author**(`author`): `void`

#### Parameters

• **author**: `string`

#### Returns

`string`

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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.

> `set` **boundingBox**(`rectangle`): `void`

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`Annotation`](Annotation.md).[`content`](Annotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)

***

### hidden

> `get` **hidden**(): `boolean`

If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.

> `set` **hidden**(`hidden`): `void`

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`id`](Annotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` `abstract` **isMaintainingAspectRatio**(): `boolean`

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)

***

### isMoveable

> `get` `abstract` **isMoveable**(): `boolean`

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)

***

### isResizable

> `get` `abstract` **isResizable**(): `boolean`

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)

***

### isRotatable

> `get` `abstract` **isRotatable**(): `boolean`

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)

***

### isSelectable

> `get` `abstract` **isSelectable**(): `boolean`

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`Annotation`](Annotation.md).[`page`](Annotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.

> `set` **renderProperties**(`v`): `void`

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`source`](Annotation.md#source)

***

### subject

> `get` **subject**(): `string`

The subject.

> `set` **subject**(`subject`): `void`

#### Parameters

• **subject**: `string`

#### Returns

`string`

***

### type

> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Inherited from

[`Annotation`](Annotation.md).[`type`](Annotation.md#type)

---

## Class: NoteAnnotation

# Class: NoteAnnotation

**`Experimental`**

A sticky note annotation

## Extends

- [`MarkupAnnotation`](MarkupAnnotation.md)

## Constructors

### new NoteAnnotation()

> **new NoteAnnotation**(`options`): [`NoteAnnotation`](NoteAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`NoteAnnotationOptions`](../interfaces/NoteAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`NoteAnnotation`](NoteAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Properties

### icon

> **icon**: [`NoteAnnotationIcon`](../enumerations/NoteAnnotationIcon.md)

**`Experimental`**

Icon to be displayed

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `StickyNoteAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `StickyNoteAnnotation`

#### Returns

`StickyNoteAnnotation`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### fillColor

> `get` **fillColor**(): `NoteAnnotationColor`

**`Experimental`**

Represents the fill color of the annotation in hexadecimal representation.

> `set` **fillColor**(`fillColor`): `void`

**`Experimental`**

#### Parameters

• **fillColor**: `NoteAnnotationColor`

#### Returns

`NoteAnnotationColor`

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### topLeft

> `get` **topLeft**(): `PdfPoint`

**`Experimental`**

Represents the top left point of the annotation on the page, specified as a `PdfPoint`.

> `set` **topLeft**(`topLeft`): `void`

**`Experimental`**

#### Parameters

• **topLeft**: `PdfPoint`

#### Returns

`PdfPoint`

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

---

## Class: PolyLineAnnotation

# Class: PolyLineAnnotation

**`Experimental`**

A poly line annotation

## Extends

- [`DrawingAnnotation`](DrawingAnnotation.md)

## Constructors

### new PolyLineAnnotation()

> **new PolyLineAnnotation**(`options`): [`PolyLineAnnotation`](PolyLineAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`PolyLineAnnotationOptions`](../interfaces/PolyLineAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`PolyLineAnnotation`](PolyLineAnnotation.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateCreated`](DrawingAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)

---

## Class: PolygonAnnotation

# Class: PolygonAnnotation

**`Experimental`**

An polygon drawing annotation

## Extends

- [`ShapeAnnotation`](ShapeAnnotation.md)

## Constructors

### new PolygonAnnotation()

> **new PolygonAnnotation**(`options`): [`PolygonAnnotation`](PolygonAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`PolygonAnnotationOptions`](../interfaces/PolygonAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`PolygonAnnotation`](PolygonAnnotation.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateCreated`](ShapeAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)

---

## Class: RectangleAnnotation

# Class: RectangleAnnotation

**`Experimental`**

A rectangle drawing annotation

## Extends

- [`ShapeAnnotation`](ShapeAnnotation.md)

## Constructors

### new RectangleAnnotation()

> **new RectangleAnnotation**(`options`): [`RectangleAnnotation`](RectangleAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`RectangleAnnotationOptions`](../interfaces/RectangleAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`RectangleAnnotation`](RectangleAnnotation.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`constructor`](ShapeAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`stroke`](ShapeAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`__annotation`](ShapeAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`author`](ShapeAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`blendMode`](ShapeAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`boundingBox`](ShapeAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`content`](ShapeAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateCreated`](ShapeAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`dateModified`](ShapeAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hasChanges`](ShapeAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`hidden`](ShapeAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`id`](ShapeAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`interactive`](ShapeAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isAdded`](ShapeAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMaintainingAspectRatio`](ShapeAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMarkupAnnotation`](ShapeAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isModified`](ShapeAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isMoveable`](ShapeAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isResizable`](ShapeAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isRotatable`](ShapeAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isSelectable`](ShapeAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`isWidgetAnnotation`](ShapeAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`locked`](ShapeAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`opacity`](ShapeAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`page`](ShapeAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`pageNumber`](ShapeAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`privateData`](ShapeAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`renderProperties`](ShapeAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`source`](ShapeAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`ShapeAnnotation`](ShapeAnnotation.md).[`subject`](ShapeAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`ShapeAnnotation`](ShapeAnnotation.md).[`type`](ShapeAnnotation.md#type)

---

## Class: `abstract` ShapeAnnotation

# Class: `abstract` ShapeAnnotation

**`Experimental`**

Base class for shape annotations

## Extends

- [`DrawingAnnotation`](DrawingAnnotation.md)

## Extended by

- [`EllipseAnnotation`](EllipseAnnotation.md)
- [`PolygonAnnotation`](PolygonAnnotation.md)
- [`RectangleAnnotation`](RectangleAnnotation.md)

## Constructors

### new ShapeAnnotation()

> **new ShapeAnnotation**(`options`): [`ShapeAnnotation`](ShapeAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`ShapeAnnotationOptions`](../interfaces/ShapeAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`ShapeAnnotation`](ShapeAnnotation.md)

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`constructor`](DrawingAnnotation.md#constructors)

## Properties

### stroke

> **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

**`Experimental`**

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`stroke`](DrawingAnnotation.md#stroke)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `MarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `MarkupAnnotation`

#### Returns

`MarkupAnnotation`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`__annotation`](DrawingAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`author`](DrawingAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`blendMode`](DrawingAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`boundingBox`](DrawingAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`content`](DrawingAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateCreated`](DrawingAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`dateModified`](DrawingAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hasChanges`](DrawingAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`hidden`](DrawingAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`id`](DrawingAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`interactive`](DrawingAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isAdded`](DrawingAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMaintainingAspectRatio`](DrawingAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMarkupAnnotation`](DrawingAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isModified`](DrawingAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`isMoveable`](DrawingAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`isResizable`](DrawingAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`isRotatable`](DrawingAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`DrawingAnnotation`](DrawingAnnotation.md).[`isSelectable`](DrawingAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`isWidgetAnnotation`](DrawingAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`locked`](DrawingAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`opacity`](DrawingAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`page`](DrawingAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`pageNumber`](DrawingAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`privateData`](DrawingAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`renderProperties`](DrawingAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`source`](DrawingAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`subject`](DrawingAnnotation.md#subject)

***

### type

> `get` `abstract` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Inherited from

[`DrawingAnnotation`](DrawingAnnotation.md).[`type`](DrawingAnnotation.md#type)

---

## Class: StampAnnotation

# Class: StampAnnotation

Base class for all stamp annotations

## Extends

- [`MarkupAnnotation`](MarkupAnnotation.md)

## Constructors

### new StampAnnotation()

> **new StampAnnotation**(`options`): [`StampAnnotation`](StampAnnotation.md)

Creates a new `StampAnnotation` instance.

#### Parameters

• **options**: [`StampAnnotationOptions`](../interfaces/StampAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`StampAnnotation`](StampAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `StampAnnotation`

> `set` **\_\_annotation**(`v`): `void`

#### Parameters

• **v**: `StampAnnotation`

#### Returns

`StampAnnotation`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

The author.

> `set` **author**(`author`): `void`

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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.

> `set` **boundingBox**(`rectangle`): `void`

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### data

> `get` **data**(): [`StampData`](../type-aliases/StampData.md)

An object representing the stamp annotation data, which depends on the subtype.

#### Returns

[`StampData`](../type-aliases/StampData.md)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `get` **hidden**(): `boolean`

If set to true, the annotation will not be displayed or printed, and it will not allow interaction with the user.

> `set` **hidden**(`hidden`): `void`

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

Object which encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its visibility, interactivity, and other rendering behaviors.

> `set` **renderProperties**(`v`): `void`

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

The subject.

> `set` **subject**(`subject`): `void`

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

## Methods

### rebuild()

> **rebuild**(`data`): `Promise`\

**`Experimental`**

Update stamp data and rebuild the annotation while keeping history and replies.

#### Parameters

• **data**: [`StampData`](../type-aliases/StampData.md)

#### Returns

`Promise`\

---

## Class: TextMarkupAnnotation

# Class: TextMarkupAnnotation

**`Experimental`**

Base class for text markup annotations

## Extends

- [`MarkupAnnotation`](MarkupAnnotation.md)

## Constructors

### new TextMarkupAnnotation()

> **new TextMarkupAnnotation**(`options`): [`TextMarkupAnnotation`](TextMarkupAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`TextMarkupAnnotationOptions`](../interfaces/TextMarkupAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`TextMarkupAnnotation`](TextMarkupAnnotation.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`constructor`](MarkupAnnotation.md#constructors)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `TextMarkupAnnotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `TextMarkupAnnotation`

#### Returns

`TextMarkupAnnotation`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`__annotation`](MarkupAnnotation.md#__annotation)

***

### author

> `get` **author**(): `string`

**`Experimental`**

The author.

> `set` **author**(`author`): `void`

**`Experimental`**

#### Parameters

• **author**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`author`](MarkupAnnotation.md#author)

***

### blendMode

> `get` **blendMode**(): [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

> `set` **blendMode**(`blendMode`): `void`

**`Experimental`**

#### Parameters

• **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Returns

[`BlendMode`](../../Drawing/enumerations/BlendMode.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`blendMode`](MarkupAnnotation.md#blendmode)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`boundingBox`](MarkupAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`content`](MarkupAnnotation.md#content)

***

### dateCreated

> `get` **dateCreated**(): `void`

**`Experimental`**

Date and time the annotation was created.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateCreated`](MarkupAnnotation.md#datecreated)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`dateModified`](MarkupAnnotation.md#datemodified)

***

### fillColor

> `get` **fillColor**(): [`RgbColor`](../../Drawing/classes/RgbColor.md)

**`Experimental`**

Retrieves the fill color used in the annotation.

> `set` **fillColor**(`v`): `void`

**`Experimental`**

Sets the fill color for the annotation.

#### Parameters

• **v**: [`RgbColor`](../../Drawing/classes/RgbColor.md)

The new [RgbColor](../../Drawing/classes/RgbColor.md) to apply to the annotation.

#### Returns

[`RgbColor`](../../Drawing/classes/RgbColor.md)

The [RgbColor](../../Drawing/classes/RgbColor.md) representing the annotation's fill color.

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hasChanges`](MarkupAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`hidden`](MarkupAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`id`](MarkupAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`interactive`](MarkupAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isAdded`](MarkupAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMaintainingAspectRatio`](MarkupAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMarkupAnnotation`](MarkupAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isModified`](MarkupAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isMoveable`](MarkupAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isResizable`](MarkupAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isRotatable`](MarkupAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`isSelectable`](MarkupAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`isWidgetAnnotation`](MarkupAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`locked`](MarkupAnnotation.md#locked)

***

### opacity

> `get` **opacity**(): `number`

**`Experimental`**

Annotation opacity

> `set` **opacity**(`opacity`): `void`

**`Experimental`**

#### Parameters

• **opacity**: `number`

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`opacity`](MarkupAnnotation.md#opacity)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`page`](MarkupAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`pageNumber`](MarkupAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`privateData`](MarkupAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`renderProperties`](MarkupAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`source`](MarkupAnnotation.md#source)

***

### subject

> `get` **subject**(): `string`

**`Experimental`**

The subject.

> `set` **subject**(`subject`): `void`

**`Experimental`**

#### Parameters

• **subject**: `string`

#### Returns

`string`

#### Inherited from

[`MarkupAnnotation`](MarkupAnnotation.md).[`subject`](MarkupAnnotation.md#subject)

***

### subtype

> `get` **subtype**(): `TextMarkupType`

**`Experimental`**

Retrieves the type of markup applied by this annotation.

#### Returns

`TextMarkupType`

The TextMarkupType representing how the text is marked,
such as highlight, underline, strikethrough, or squiggly.

***

### textMarkupArea

> `get` **textMarkupArea**(): [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\[]

**`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`](../../Geometry/classes/Quadrilateral.md)\[]

An array of [Quadrilateral](../../Geometry/classes/Quadrilateral.md) defining the marked-up area.

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`MarkupAnnotation`](MarkupAnnotation.md).[`type`](MarkupAnnotation.md#type)

***

### underlyingText

> `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.

---

## Class: WatermarkAnnotation

# Class: WatermarkAnnotation

**`Experimental`**

A watermark annotation

## Extends

- [`Annotation`](Annotation.md)

## Constructors

### new WatermarkAnnotation()

> **new WatermarkAnnotation**(`options`): [`WatermarkAnnotation`](WatermarkAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`WatermarkAnnotationOptions`](../interfaces/WatermarkAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`WatermarkAnnotation`](WatermarkAnnotation.md)

#### Overrides

[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the watermark annotation is clicked on

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`Annotation`](Annotation.md).[`content`](Annotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`id`](Annotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`Annotation`](Annotation.md).[`page`](Annotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`source`](Annotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Watermark`

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`Annotation`](Annotation.md).[`type`](Annotation.md#type)

---

## Class: WidgetAnnotation

# Class: WidgetAnnotation

**`Experimental`**

A widget annotation

## Extends

- [`Annotation`](Annotation.md)

## Extended by

- [`ButtonWidget`](../../Forms/classes/ButtonWidget.md)
- [`CheckBoxWidget`](../../Forms/classes/CheckBoxWidget.md)
- [`ComboBoxWidget`](../../Forms/classes/ComboBoxWidget.md)
- [`FormWidget`](../../Forms/classes/FormWidget.md)
- [`ListBoxWidget`](../../Forms/classes/ListBoxWidget.md)
- [`RadioButtonWidget`](../../Forms/classes/RadioButtonWidget.md)
- [`TextBoxWidget`](../../Forms/classes/TextBoxWidget.md)

## Constructors

### new WidgetAnnotation()

> **new WidgetAnnotation**(`options`): [`WidgetAnnotation`](WidgetAnnotation.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`WidgetAnnotation`](WidgetAnnotation.md)

#### Overrides

[`Annotation`](Annotation.md).[`constructor`](Annotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`Annotation`](Annotation.md).[`__annotation`](Annotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`Annotation`](Annotation.md).[`boundingBox`](Annotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`Annotation`](Annotation.md).[`content`](Annotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`Annotation`](Annotation.md).[`dateModified`](Annotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hasChanges`](Annotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`hidden`](Annotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`id`](Annotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`interactive`](Annotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isAdded`](Annotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMaintainingAspectRatio`](Annotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMarkupAnnotation`](Annotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`Annotation`](Annotation.md).[`isModified`](Annotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isMoveable`](Annotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isResizable`](Annotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isRotatable`](Annotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isSelectable`](Annotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Overrides

[`Annotation`](Annotation.md).[`isWidgetAnnotation`](Annotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../enumerations/AnnotationLockedState.md)

#### Inherited from

[`Annotation`](Annotation.md).[`locked`](Annotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`Annotation`](Annotation.md).[`page`](Annotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`Annotation`](Annotation.md).[`pageNumber`](Annotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`Annotation`](Annotation.md).[`privateData`](Annotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](AnnotationRenderProperties.md)

#### Inherited from

[`Annotation`](Annotation.md).[`renderProperties`](Annotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`Annotation`](Annotation.md).[`source`](Annotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../enumerations/AnnotationType.md)

#### Overrides

[`Annotation`](Annotation.md).[`type`](Annotation.md#type)

---

## Enumeration: AnnotationLockedState

# 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

# 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`

***

### PolyLine

> **PolyLine**: `10`

***

### Polygon

> **Polygon**: `9`

***

### Popup

> **Popup**: `14`

***

### PrinterMark

> **PrinterMark**: `20`

***

### Redact

> **Redact**: `23`

***

### Screen

> **Screen**: `19`

***

### Sound

> **Sound**: `16`

***

### Square

> **Square**: `7`

***

### Stamp

> **Stamp**: `11`

***

### Text

> **Text**: `0`

***

### TextMarkup

> **TextMarkup**: `4`

***

### TrapNet

> **TrapNet**: `21`

***

### Watermark

> **Watermark**: `22`

***

### WebLink

> **WebLink**: `2`

***

### Widget

> **Widget**: `18`

---

## Enumeration: FileAttachmentAnnotationIcon

# 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

# 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: PredefinedTextStampType

# 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: StampAnnotationSubtype

# 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

# Enumeration: StampColor

An enum defining stamp colors.

## Enumeration Members

### Blue

> **Blue**: `2`

***

### Green

> **Green**: `1`

***

### Red

> **Red**: `0`

---

## Annotations

# Annotations

## Index

### Enumerations

- [AnnotationLockedState](enumerations/AnnotationLockedState.md)
- [AnnotationType](enumerations/AnnotationType.md)
- [FileAttachmentAnnotationIcon](enumerations/FileAttachmentAnnotationIcon.md)
- [NoteAnnotationIcon](enumerations/NoteAnnotationIcon.md)
- [PredefinedTextStampType](enumerations/PredefinedTextStampType.md)
- [StampAnnotationSubtype](enumerations/StampAnnotationSubtype.md)
- [StampColor](enumerations/StampColor.md)

### Classes

- [Annotation](classes/Annotation.md)
- [AnnotationRenderProperties](classes/AnnotationRenderProperties.md)
- [CaretAnnotation](classes/CaretAnnotation.md)
- [DrawingAnnotation](classes/DrawingAnnotation.md)
- [EllipseAnnotation](classes/EllipseAnnotation.md)
- [FileAttachmentAnnotation](classes/FileAttachmentAnnotation.md)
- [FreeTextAnnotation](classes/FreeTextAnnotation.md)
- [InkAnnotation](classes/InkAnnotation.md)
- [LineAnnotation](classes/LineAnnotation.md)
- [LinkAnnotation](classes/LinkAnnotation.md)
- [MarkupAnnotation](classes/MarkupAnnotation.md)
- [NoteAnnotation](classes/NoteAnnotation.md)
- [PolyLineAnnotation](classes/PolyLineAnnotation.md)
- [PolygonAnnotation](classes/PolygonAnnotation.md)
- [RectangleAnnotation](classes/RectangleAnnotation.md)
- [ShapeAnnotation](classes/ShapeAnnotation.md)
- [StampAnnotation](classes/StampAnnotation.md)
- [TextMarkupAnnotation](classes/TextMarkupAnnotation.md)
- [WatermarkAnnotation](classes/WatermarkAnnotation.md)
- [WidgetAnnotation](classes/WidgetAnnotation.md)

### Interfaces

- [AnnotationOptions](interfaces/AnnotationOptions.md)
- [CaretAnnotationOptions](interfaces/CaretAnnotationOptions.md)
- [CustomStampAnnotationOptions](interfaces/CustomStampAnnotationOptions.md)
- [CustomTextStampAnnotationOptions](interfaces/CustomTextStampAnnotationOptions.md)
- [DrawingAnnotationOptions](interfaces/DrawingAnnotationOptions.md)
- [EllipseAnnotationOptions](interfaces/EllipseAnnotationOptions.md)
- [FileAttachmentAnnotationOptions](interfaces/FileAttachmentAnnotationOptions.md)
- [FreeTextAnnotationOptions](interfaces/FreeTextAnnotationOptions.md)
- [ImageStampAnnotationOptions](interfaces/ImageStampAnnotationOptions.md)
- [InkAnnotationOptions](interfaces/InkAnnotationOptions.md)
- [LineAnnotationOptions](interfaces/LineAnnotationOptions.md)
- [LinkAnnotationOptions](interfaces/LinkAnnotationOptions.md)
- [MarkupAnnotationOptions](interfaces/MarkupAnnotationOptions.md)
- [NoteAnnotationOptions](interfaces/NoteAnnotationOptions.md)
- [PdfStampAnnotationOptions](interfaces/PdfStampAnnotationOptions.md)
- [PolyLineAnnotationOptions](interfaces/PolyLineAnnotationOptions.md)
- [PolygonAnnotationOptions](interfaces/PolygonAnnotationOptions.md)
- [PredefinedTextStampAnnotationOptions](interfaces/PredefinedTextStampAnnotationOptions.md)
- [RectangleAnnotationOptions](interfaces/RectangleAnnotationOptions.md)
- [ShapeAnnotationOptions](interfaces/ShapeAnnotationOptions.md)
- [StampAnnotationOptions](interfaces/StampAnnotationOptions.md)
- [TextMarkupAnnotationOptions](interfaces/TextMarkupAnnotationOptions.md)
- [WatermarkAnnotationOptions](interfaces/WatermarkAnnotationOptions.md)
- [WidgetAnnotationOptions](interfaces/WidgetAnnotationOptions.md)

### Type Aliases

- [StampData](type-aliases/StampData.md)

---

## Interface: AnnotationOptions

# Interface: AnnotationOptions

Base options for all annotations

## Extended by

- [`LinkAnnotationOptions`](LinkAnnotationOptions.md)
- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)
- [`NoteAnnotationOptions`](NoteAnnotationOptions.md)
- [`WatermarkAnnotationOptions`](WatermarkAnnotationOptions.md)
- [`WidgetAnnotationOptions`](WidgetAnnotationOptions.md)

## Properties

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](../../../classes/Page.md)

Page in which the annotation is embedded.

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

---

## Interface: CaretAnnotationOptions

# Interface: CaretAnnotationOptions

Base options for all annotations

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

---

## Interface: CustomStampAnnotationOptions

# Interface: CustomStampAnnotationOptions

**`Experimental`**

An interface specific to Custom stamp annotations, defining custom content used for creating the annotation.

## Properties

### content

> **content**: [`PdfContent`](../../Drawing/interfaces/PdfContent.md)

**`Experimental`**

***

### subtype

> **subtype**: [`Custom`](../enumerations/StampAnnotationSubtype.md#custom)

**`Experimental`**

---

## Interface: CustomTextStampAnnotationOptions

# Interface: CustomTextStampAnnotationOptions

An interface specific to custom text stamp annotations, defining the text and color.

## Properties

### color

> **color**: [`StampColor`](../enumerations/StampColor.md)

***

### subtype

> **subtype**: [`CustomText`](../enumerations/StampAnnotationSubtype.md#customtext)

***

### text

> **text**: `string`

---

## Interface: DrawingAnnotationOptions

# Interface: DrawingAnnotationOptions

Base options for all annotations

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Extended by

- [`InkAnnotationOptions`](InkAnnotationOptions.md)
- [`LineAnnotationOptions`](LineAnnotationOptions.md)
- [`PolyLineAnnotationOptions`](PolyLineAnnotationOptions.md)
- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

---

## Interface: EllipseAnnotationOptions

# Interface: EllipseAnnotationOptions

## Extends

- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#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`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)

***

### fill?

> `optional` **fill**: `string`

annotation fill

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)

---

## Interface: FileAttachmentAnnotationOptions

# Interface: FileAttachmentAnnotationOptions

Base options for all annotations

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### icon?

> `optional` **icon**: [`FileAttachmentAnnotationIcon`](../enumerations/FileAttachmentAnnotationIcon.md)

icon

#### Default

```ts
PushPin
```

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

---

## Interface: FreeTextAnnotationOptions

# Interface: FreeTextAnnotationOptions

Base options for all annotations

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### backgroundColor?

> `optional` **backgroundColor**: `string`

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### rotation?

> `optional` **rotation**: `number`

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

---

## Interface: ImageStampAnnotationOptions

# Interface: ImageStampAnnotationOptions

An interface specific to image stamp annotations, defining the registered image used for creating the annotation.

## Properties

### image

> **image**: [`PdfImage`](../../../interfaces/PdfImage.md)

***

### subtype

> **subtype**: [`Image`](../enumerations/StampAnnotationSubtype.md#image)

---

## Interface: InkAnnotationOptions

# Interface: InkAnnotationOptions

Base options for all annotations

## Extends

- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#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`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)

---

## Interface: LineAnnotationOptions

# Interface: LineAnnotationOptions

Base options for all annotations

## Extends

- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#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`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)

---

## Interface: LinkAnnotationOptions

# Interface: LinkAnnotationOptions

Base options for all annotations

## Extends

- [`AnnotationOptions`](AnnotationOptions.md)

## Properties

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#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`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)

---

## Interface: MarkupAnnotationOptions

# Interface: MarkupAnnotationOptions

Base options for all annotations

## Extends

- [`AnnotationOptions`](AnnotationOptions.md)

## Extended by

- [`CaretAnnotationOptions`](CaretAnnotationOptions.md)
- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)
- [`FileAttachmentAnnotationOptions`](FileAttachmentAnnotationOptions.md)
- [`FreeTextAnnotationOptions`](FreeTextAnnotationOptions.md)
- [`StampAnnotationOptions`](StampAnnotationOptions.md)
- [`TextMarkupAnnotationOptions`](TextMarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#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`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)

***

### subject?

> `optional` **subject**: `string`

---

## Interface: NoteAnnotationOptions

# Interface: NoteAnnotationOptions

Base options for all annotations

## Extends

- [`AnnotationOptions`](AnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#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`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)

***

### fillColor?

> `optional` **fillColor**: `NoteAnnotationColor`

Represents the fill color of the annotation in hexadecimal representation.

#### Default Value

```ts
"'#FFECB3'"
```

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#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

# 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`](../../Drawing/interfaces/PdfContent.md)

***

### subtype

> **subtype**: [`Pdf`](../enumerations/StampAnnotationSubtype.md#pdf)

---

## Interface: PolyLineAnnotationOptions

# Interface: PolyLineAnnotationOptions

Base options for all annotations

## Extends

- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#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`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)

---

## Interface: PolygonAnnotationOptions

# Interface: PolygonAnnotationOptions

## Extends

- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#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`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)

***

### fill?

> `optional` **fill**: `string`

annotation fill

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)

---

## Interface: PredefinedTextStampAnnotationOptions

# Interface: PredefinedTextStampAnnotationOptions

An interface specific to predefined text stamp annotations, defining the predefined text stamp type.

## Properties

### predefinedTextStampType

> **predefinedTextStampType**: [`PredefinedTextStampType`](../enumerations/PredefinedTextStampType.md)

***

### subtype

> **subtype**: [`PredefinedText`](../enumerations/StampAnnotationSubtype.md#predefinedtext)

---

## Interface: RectangleAnnotationOptions

# Interface: RectangleAnnotationOptions

## Extends

- [`ShapeAnnotationOptions`](ShapeAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`author`](ShapeAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`blendMode`](ShapeAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](ShapeAnnotationOptions.md).[`boundingBox`](ShapeAnnotationOptions.md#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`](ShapeAnnotationOptions.md).[`content`](ShapeAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`dateModified`](ShapeAnnotationOptions.md#datemodified)

***

### fill?

> `optional` **fill**: `string`

annotation fill

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`fill`](ShapeAnnotationOptions.md#fill)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`opacity`](ShapeAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`page`](ShapeAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`privateData`](ShapeAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`renderProperties`](ShapeAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`stroke`](ShapeAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`ShapeAnnotationOptions`](ShapeAnnotationOptions.md).[`subject`](ShapeAnnotationOptions.md#subject)

---

## Interface: ShapeAnnotationOptions

# Interface: ShapeAnnotationOptions

## Extends

- [`DrawingAnnotationOptions`](DrawingAnnotationOptions.md)

## Extended by

- [`EllipseAnnotationOptions`](EllipseAnnotationOptions.md)
- [`PolygonAnnotationOptions`](PolygonAnnotationOptions.md)
- [`RectangleAnnotationOptions`](RectangleAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`author`](DrawingAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`blendMode`](DrawingAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](DrawingAnnotationOptions.md).[`boundingBox`](DrawingAnnotationOptions.md#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`](DrawingAnnotationOptions.md).[`content`](DrawingAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`dateModified`](DrawingAnnotationOptions.md#datemodified)

***

### fill?

> `optional` **fill**: `string`

annotation fill

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`opacity`](DrawingAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`page`](DrawingAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`privateData`](DrawingAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`renderProperties`](DrawingAnnotationOptions.md#renderproperties)

***

### stroke?

> `optional` **stroke**: [`Stroke`](../../Drawing/classes/Stroke.md)

annotation stroke

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`stroke`](DrawingAnnotationOptions.md#stroke)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`DrawingAnnotationOptions`](DrawingAnnotationOptions.md).[`subject`](DrawingAnnotationOptions.md#subject)

---

## Interface: StampAnnotationOptions

# Interface: StampAnnotationOptions

Base options for all annotations

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### data

> **data**: [`StampData`](../type-aliases/StampData.md)

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`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

---

## Interface: TextMarkupAnnotationOptions

# Interface: TextMarkupAnnotationOptions

Interface representing options for text markup annotations.

This interface extends [MarkupAnnotationOptions](MarkupAnnotationOptions.md) and provides additional
properties specific to text markup annotations, such as the marked area,
annotation subtype, and fill color.

## Extends

- [`MarkupAnnotationOptions`](MarkupAnnotationOptions.md)

## Properties

### author?

> `optional` **author**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`author`](MarkupAnnotationOptions.md#author)

***

### blendMode?

> `optional` **blendMode**: [`BlendMode`](../../Drawing/enumerations/BlendMode.md)

**`Experimental`**

blend mode

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`blendMode`](MarkupAnnotationOptions.md#blendmode)

***

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](MarkupAnnotationOptions.md).[`boundingBox`](MarkupAnnotationOptions.md#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`](MarkupAnnotationOptions.md).[`content`](MarkupAnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`dateModified`](MarkupAnnotationOptions.md#datemodified)

***

### fillColor?

> `optional` **fillColor**: [`RgbColor`](../../Drawing/classes/RgbColor.md)

The color used to fill the marked-up area.

***

### opacity?

> `optional` **opacity**: `number`

**`Experimental`**

annotation opacity

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`opacity`](MarkupAnnotationOptions.md#opacity)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`page`](MarkupAnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`privateData`](MarkupAnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`renderProperties`](MarkupAnnotationOptions.md#renderproperties)

***

### subject?

> `optional` **subject**: `string`

#### Inherited from

[`MarkupAnnotationOptions`](MarkupAnnotationOptions.md).[`subject`](MarkupAnnotationOptions.md#subject)

***

### subtype?

> `optional` **subtype**: `TextMarkupType`

Specifies the subtype of text markup annotation.
Determines how the text is visually marked, such as highlight, underline,
strikethrough, or squiggly.

***

### textMarkupArea?

> `optional` **textMarkupArea**: [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\[]

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

# Interface: WatermarkAnnotationOptions

Base options for all annotations

## Extends

- [`AnnotationOptions`](AnnotationOptions.md)

## Properties

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#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`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)

---

## Interface: WidgetAnnotationOptions

# Interface: WidgetAnnotationOptions

Base options for all annotations

## Extends

- [`AnnotationOptions`](AnnotationOptions.md)

## Properties

### boundingBox?

> `optional` **boundingBox**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

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`](AnnotationOptions.md).[`boundingBox`](AnnotationOptions.md#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`](AnnotationOptions.md).[`content`](AnnotationOptions.md#content)

***

### dateModified?

> `optional` **dateModified**: `Date`

The date and time when the annotation was most recently modified.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`dateModified`](AnnotationOptions.md#datemodified)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

Page in which the annotation is embedded.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`page`](AnnotationOptions.md#page)

***

### privateData?

> `optional` **privateData**: `object`

Custom data to be stored with the annotation

#### Default Value

`undefined`

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`privateData`](AnnotationOptions.md#privatedata)

***

### renderProperties?

> `optional` **renderProperties**: [`AnnotationRenderProperties`](../classes/AnnotationRenderProperties.md)

The `AnnotationRenderProperties` class encapsulates the rendering properties of a PDF annotation,
providing a set of flags that control its rendering behaviors.

#### Inherited from

[`AnnotationOptions`](AnnotationOptions.md).[`renderProperties`](AnnotationOptions.md#renderproperties)

---

## Type Alias: StampData

# Type Alias: StampData

> **StampData**: [`PredefinedTextStampAnnotationOptions`](../interfaces/PredefinedTextStampAnnotationOptions.md) \| [`CustomTextStampAnnotationOptions`](../interfaces/CustomTextStampAnnotationOptions.md) \| [`ImageStampAnnotationOptions`](../interfaces/ImageStampAnnotationOptions.md) \| [`PdfStampAnnotationOptions`](../interfaces/PdfStampAnnotationOptions.md) \| [`CustomStampAnnotationOptions`](../interfaces/CustomStampAnnotationOptions.md)

A type that represents stamp data, which can be one of the specific options for different subtypes.

---

## Enumeration: DestinationType

# 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.

---

## Destination

# Destination

## Index

### Enumerations

- [DestinationType](enumerations/DestinationType.md)

### Interfaces

- [Destination](interfaces/Destination.md)

---

## Interface: Destination

# Interface: Destination

## Properties

### destinationType

> **destinationType**: [`DestinationType`](../enumerations/DestinationType.md)

***

### page

> **page**: [`Page`](../../../classes/Page.md)

***

### rectangle?

> `optional` **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

***

### zoom?

> `optional` **zoom**: `number`

---

## Class: Canvas

# Class: Canvas

**`Experimental`**

Canvas for drawing grafics and text on a PdfPage
or a custom Annotation

## Constructors

### new Canvas()

> **new Canvas**(): [`Canvas`](Canvas.md)

**`Experimental`**

#### Returns

[`Canvas`](Canvas.md)

## Methods

### arcTo()

> **arcTo**(): `void`

**`Experimental`**

#### Returns

`void`

***

### beginPath()

> **beginPath**(): `void`

**`Experimental`**

#### Returns

`void`

***

### bezierCurveTo()

> **bezierCurveTo**(): `void`

**`Experimental`**

#### Returns

`void`

***

### drawText()

> **drawText**(): `void`

**`Experimental`**

#### Returns

`void`

***

### lineTo()

> **lineTo**(): `void`

**`Experimental`**

#### Returns

`void`

***

### moveTo()

> **moveTo**(): `void`

**`Experimental`**

#### Returns

`void`

---

## Class: Path

# Class: Path

**`Experimental`**

## Constructors

### new Path()

> **new Path**(): [`Path`](Path.md)

**`Experimental`**

#### Returns

[`Path`](Path.md)

---

## Class: PdfContentCreator

# Class: PdfContentCreator

**`Experimental`**

PdfContentCreator is used to generate content by using operations for drawing on canvas.

## Constructors

### new PdfContentCreator()

> **new PdfContentCreator**(`width`, `height`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Parameters

• **width**: `number`

• **height**: `number`

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

## Methods

### beginPath()

> **beginPath**(): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### closePath()

> **closePath**(): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### drawImage()

#### drawImage(image, dx, dy)

> **drawImage**(`image`, `dx`, `dy`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

##### Parameters

• **image**: `Blob`

• **dx**: `number`

• **dy**: `number`

##### Returns

[`PdfContentCreator`](PdfContentCreator.md)

#### drawImage(image, dx, dy, dWidth, dHeight)

> **drawImage**(`image`, `dx`, `dy`, `dWidth`, `dHeight`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

##### Parameters

• **image**: `Blob`

• **dx**: `number`

• **dy**: `number`

• **dWidth**: `number`

• **dHeight**: `number`

##### Returns

[`PdfContentCreator`](PdfContentCreator.md)

#### drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

> **drawImage**(`image`, `sx`, `sy`, `sWidth`, `sHeight`, `dx`, `dy`, `dWidth`, `dHeight`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

##### Parameters

• **image**: `Blob`

• **sx**: `number`

• **sy**: `number`

• **sWidth**: `number`

• **sHeight**: `number`

• **dx**: `number`

• **dy**: `number`

• **dWidth**: `number`

• **dHeight**: `number`

##### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### generateContent()

> **generateContent**(): [`PdfContent`](../interfaces/PdfContent.md)

**`Experimental`**

#### Returns

[`PdfContent`](../interfaces/PdfContent.md)

***

### lineTo()

> **lineTo**(`x`, `y`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Parameters

• **x**: `number`

• **y**: `number`

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### moveTo()

> **moveTo**(`x`, `y`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Parameters

• **x**: `number`

• **y**: `number`

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### rotate()

> **rotate**(`deg`): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Parameters

• **deg**: `number`

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

***

### stroke()

> **stroke**(): [`PdfContentCreator`](PdfContentCreator.md)

**`Experimental`**

#### Returns

[`PdfContentCreator`](PdfContentCreator.md)

---

## Class: RgbColor

# Class: RgbColor

Represents a color with red, green and blue components.

## Extended by

- [`RgbaColor`](RgbaColor.md)

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\

## Constructors

### new RgbColor()

> **new RgbColor**(`colorString`): [`RgbColor`](RgbColor.md)

Creates a new RgbColor instance from a string representation (hex, rgb or hsl).

#### Parameters

• **colorString**: `string`

The string representation of the color.

#### Returns

[`RgbColor`](RgbColor.md)

#### Throws

If the input string is not a valid color representation.

### new RgbColor()

> **new RgbColor**(`r`?, `g`?, `b`?): [`RgbColor`](RgbColor.md)

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`](RgbColor.md)

## 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` **blue**(): `number`

The intensity of blue in the described color as a value 0-255.

#### Returns

`number`

***

### green

> `get` **green**(): `number`

The intensity of green in the described color as a value 0-255.

#### Returns

`number`

***

### red

> `get` **red**(): `number`

The intensity of red in the described color as a value 0-255.

#### Returns

`number`

## Methods

### clone()

> **clone**(): [`RgbColor`](RgbColor.md)

Creates a deep copy of the object.

#### Returns

[`RgbColor`](RgbColor.md)

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)

***

### setRGB()

> **setRGB**(`red`, `green`, `blue`): `void`

Set a new color with all components at once

#### Parameters

• **red**: `number`

• **green**: `number`

• **blue**: `number`

#### Returns

`void`

***

### toHexString()

> **toHexString**(): `string`

Converts the color to a hexadecimal string

#### Returns

`string`

A string representation of the color in hexadecimal

#### Example

```ts
#330000
```

***

### toRgbString()

> **toRgbString**(): `string`

Converts the color to a CSS-formatted RGB string.

#### Returns

`string`

A string representation of the color in RGB format.

***

### toRgbaString()

> **toRgbaString**(): `string`

Converts the color to a CSS-formatted RGBA string.

#### Returns

`string`

A string representation of the color in RGBA format.

---

## Class: RgbaColor

# Class: RgbaColor

Represents a color with red, green, blue, and alpha components.

## Extends

- [`RgbColor`](RgbColor.md)

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\

## Constructors

### new RgbaColor()

> **new RgbaColor**(`colorString`): [`RgbaColor`](RgbaColor.md)

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`](RgbaColor.md)

#### Throws

If the input string is not a valid color representation.

#### Overrides

[`RgbColor`](RgbColor.md).[`constructor`](RgbColor.md#constructors)

### new RgbaColor()

> **new RgbaColor**(`r`?, `g`?, `b`?, `a`?): [`RgbaColor`](RgbaColor.md)

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`](RgbaColor.md)

#### Overrides

[`RgbColor`](RgbColor.md).[`constructor`](RgbColor.md#constructors)

## 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`](RgbColor.md).[`b`](RgbColor.md#b)

***

### g

> **g**: `number` = `0`

The green component of the color (0 to 255).

#### Inherited from

[`RgbColor`](RgbColor.md).[`g`](RgbColor.md#g)

***

### r

> **r**: `number` = `0`

The red component of the color (0 to 255).

#### Inherited from

[`RgbColor`](RgbColor.md).[`r`](RgbColor.md#r)

## Accessors

### blue

> `get` **blue**(): `number`

The intensity of blue in the described color as a value 0-255.

#### Returns

`number`

#### Inherited from

[`RgbColor`](RgbColor.md).[`blue`](RgbColor.md#blue)

***

### green

> `get` **green**(): `number`

The intensity of green in the described color as a value 0-255.

#### Returns

`number`

#### Inherited from

[`RgbColor`](RgbColor.md).[`green`](RgbColor.md#green)

***

### red

> `get` **red**(): `number`

The intensity of red in the described color as a value 0-255.

#### Returns

`number`

#### Inherited from

[`RgbColor`](RgbColor.md).[`red`](RgbColor.md#red)

## Methods

### clone()

> **clone**(): [`RgbaColor`](RgbaColor.md)

Creates a deep copy of the object.

#### Returns

[`RgbaColor`](RgbaColor.md)

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)

#### Overrides

[`RgbColor`](RgbColor.md).[`clone`](RgbColor.md#clone)

***

### setRGB()

> **setRGB**(`red`, `green`, `blue`): `void`

Set a new color with all components at once

#### Parameters

• **red**: `number`

• **green**: `number`

• **blue**: `number`

#### Returns

`void`

#### Inherited from

[`RgbColor`](RgbColor.md).[`setRGB`](RgbColor.md#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`](RgbColor.md).[`toHexString`](RgbColor.md#tohexstring)

***

### 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`](RgbColor.md).[`toRgbString`](RgbColor.md#torgbstring)

***

### 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`](RgbColor.md).[`toRgbaString`](RgbColor.md#torgbastring)

---

## Class: Stroke

# Class: Stroke

**`Experimental`**

## Constructors

### new Stroke()

> **new Stroke**(): [`Stroke`](Stroke.md)

**`Experimental`**

#### Returns

[`Stroke`](Stroke.md)

## Properties

### color

> **color**: [`RgbaColor`](RgbaColor.md)

**`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

# 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: LineEnding

# 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

---

## Drawing

# Drawing

## Index

### Namespaces

- [Util](namespaces/Util/index.md)

### Enumerations

- [BlendMode](enumerations/BlendMode.md)
- [LineEnding](enumerations/LineEnding.md)

### Classes

- [Canvas](classes/Canvas.md)
- [Path](classes/Path.md)
- [PdfContentCreator](classes/PdfContentCreator.md)
- [RgbColor](classes/RgbColor.md)
- [RgbaColor](classes/RgbaColor.md)
- [Stroke](classes/Stroke.md)

### Interfaces

- [PdfContent](interfaces/PdfContent.md)

---

## Interface: PdfContent

# Interface: PdfContent

**`Experimental`**

An interface representing PDF content.

---

## Function: drawLine()

# 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()

# 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()

# 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`](../../../../Geometry/classes/Quadrilateral.md)\

A `Quadrilateral` object representing the vertices of the quadrilateral.

• **color**: `string`

The fill color of the quadrilateral.

## Returns

`void`

---

## Function: drawQuadrilateralOutline()

# 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`](../../../../Geometry/classes/Quadrilateral.md)\

A `Quadrilateral` object representing the vertices of the quadrilateral.

• **color**: `string`

The color of the quadrilateral outline.

## Returns

`void`

---

## Util

# Util

## Index

### Functions

- [drawLine](functions/drawLine.md)
- [drawPoint](functions/drawPoint.md)
- [drawQuadrilateralArea](functions/drawQuadrilateralArea.md)
- [drawQuadrilateralOutline](functions/drawQuadrilateralOutline.md)

---

## Class: ButtonWidget

# Class: ButtonWidget

**`Experimental`**

A button widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new ButtonWidget()

> **new ButtonWidget**(`options`): [`ButtonWidget`](ButtonWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`ButtonWidget`](ButtonWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: CheckBoxWidget

# Class: CheckBoxWidget

**`Experimental`**

A checkbox widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new CheckBoxWidget()

> **new CheckBoxWidget**(`options`): [`CheckBoxWidget`](CheckBoxWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`CheckBoxWidget`](CheckBoxWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: ComboBoxWidget

# Class: ComboBoxWidget

**`Experimental`**

A combo box widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new ComboBoxWidget()

> **new ComboBoxWidget**(`options`): [`ComboBoxWidget`](ComboBoxWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`ComboBoxWidget`](ComboBoxWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: FormWidget

# Class: FormWidget

**`Experimental`**

A form widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new FormWidget()

> **new FormWidget**(`options`): [`FormWidget`](FormWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`FormWidget`](FormWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: ListBoxWidget

# Class: ListBoxWidget

**`Experimental`**

A list box widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new ListBoxWidget()

> **new ListBoxWidget**(`options`): [`ListBoxWidget`](ListBoxWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`ListBoxWidget`](ListBoxWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: RadioButtonWidget

# Class: RadioButtonWidget

**`Experimental`**

A radio button widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new RadioButtonWidget()

> **new RadioButtonWidget**(`options`): [`RadioButtonWidget`](RadioButtonWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`RadioButtonWidget`](RadioButtonWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Class: TextBoxWidget

# Class: TextBoxWidget

**`Experimental`**

A text box widget annotation

## Extends

- [`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md)

## Constructors

### new TextBoxWidget()

> **new TextBoxWidget**(`options`): [`TextBoxWidget`](TextBoxWidget.md)

**`Experimental`**

#### Parameters

• **options**: [`WidgetAnnotationOptions`](../../Annotations/interfaces/WidgetAnnotationOptions.md)

Options used to initialize annotation.

#### Returns

[`TextBoxWidget`](TextBoxWidget.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`constructor`](../../Annotations/classes/WidgetAnnotation.md#constructors)

## Properties

### action

> **action**: [`Action`](../../Actions/classes/Action.md)

**`Experimental`**

The action that is performed when the widget annotation is clicked on

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`action`](../../Annotations/classes/WidgetAnnotation.md#action)

## Accessors

### \_\_annotation

> `get` **\_\_annotation**(): `Annotation`

**`Experimental`**

> `set` **\_\_annotation**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: `Annotation`

#### Returns

`Annotation`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`__annotation`](../../Annotations/classes/WidgetAnnotation.md#__annotation)

***

### boundingBox

> `get` **boundingBox**(): [`Rectangle`](../../Geometry/classes/Rectangle.md)\

**`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.

> `set` **boundingBox**(`rectangle`): `void`

**`Experimental`**

#### Parameters

• **rectangle**: [`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Returns

[`Rectangle`](../../Geometry/classes/Rectangle.md)\

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`boundingBox`](../../Annotations/classes/WidgetAnnotation.md#boundingbox)

***

### content

> `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.

> `set` **content**(`content`): `void`

**`Experimental`**

#### Parameters

• **content**: `string`

#### Returns

`string`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`content`](../../Annotations/classes/WidgetAnnotation.md#content)

***

### dateModified

> `get` **dateModified**(): `Date`

**`Experimental`**

The date and time when the annotation was most recently modified.

> `set` **dateModified**(`date`): `void`

**`Experimental`**

#### Parameters

• **date**: `Date`

#### Returns

`Date`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`dateModified`](../../Annotations/classes/WidgetAnnotation.md#datemodified)

***

### hasChanges

> `get` **hasChanges**(): `boolean`

**`Experimental`**

Indicates if the annotation has been changed since the document was opened

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hasChanges`](../../Annotations/classes/WidgetAnnotation.md#haschanges)

***

### hidden

> `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.

> `set` **hidden**(`hidden`): `void`

**`Experimental`**

#### Parameters

• **hidden**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`hidden`](../../Annotations/classes/WidgetAnnotation.md#hidden)

***

### id

> `get` **id**(): `void`

**`Experimental`**

A unique identifier for the annotation.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`id`](../../Annotations/classes/WidgetAnnotation.md#id)

***

### interactive

> `get` **interactive**(): `boolean`

**`Experimental`**

Specifies whether the annotation allows user interaction.

> `set` **interactive**(`interactive`): `void`

**`Experimental`**

#### Parameters

• **interactive**: `boolean`

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`interactive`](../../Annotations/classes/WidgetAnnotation.md#interactive)

***

### isAdded

> `get` **isAdded**(): `boolean`

**`Experimental`**

Indicates whether the annotation was added to a page

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isAdded`](../../Annotations/classes/WidgetAnnotation.md#isadded)

***

### isMaintainingAspectRatio

> `get` **isMaintainingAspectRatio**(): `boolean`

**`Experimental`**

Indicates if the annotation is maintaining its aspect ratio

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMaintainingAspectRatio`](../../Annotations/classes/WidgetAnnotation.md#ismaintainingaspectratio)

***

### isMarkupAnnotation

> `get` **isMarkupAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a markup annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMarkupAnnotation`](../../Annotations/classes/WidgetAnnotation.md#ismarkupannotation)

***

### isModified

> `get` **isModified**(): `boolean`

**`Experimental`**

Indicates if the annotation has changes that have not yet been saved to
the document

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isModified`](../../Annotations/classes/WidgetAnnotation.md#ismodified)

***

### isMoveable

> `get` **isMoveable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be moved by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isMoveable`](../../Annotations/classes/WidgetAnnotation.md#ismoveable)

***

### isResizable

> `get` **isResizable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be resized by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isResizable`](../../Annotations/classes/WidgetAnnotation.md#isresizable)

***

### isRotatable

> `get` **isRotatable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be rotated by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isRotatable`](../../Annotations/classes/WidgetAnnotation.md#isrotatable)

***

### isSelectable

> `get` **isSelectable**(): `boolean`

**`Experimental`**

Indicates if the annotation can be selected by the user

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isSelectable`](../../Annotations/classes/WidgetAnnotation.md#isselectable)

***

### isWidgetAnnotation

> `get` **isWidgetAnnotation**(): `boolean`

**`Experimental`**

Indicates if the annotation is a widget annotation

#### Returns

`boolean`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`isWidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md#iswidgetannotation)

***

### locked

> `get` **locked**(): [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

**`Experimental`**

Represents the locked state of the annotation.

> `set` **locked**(`locked`): `void`

**`Experimental`**

#### Parameters

• **locked**: [`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Returns

[`AnnotationLockedState`](../../Annotations/enumerations/AnnotationLockedState.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`locked`](../../Annotations/classes/WidgetAnnotation.md#locked)

***

### page

> `get` **page**(): [`Page`](../../../classes/Page.md)

**`Experimental`**

Page in which the annotation is embedded.

> `set` **page**(`page`): `void`

**`Experimental`**

Set the page in which the annotation is embedded.

#### Parameters

• **page**: [`Page`](../../../classes/Page.md)

The page to set as the annotation's page.

#### Returns

[`Page`](../../../classes/Page.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`page`](../../Annotations/classes/WidgetAnnotation.md#page)

***

### pageNumber

> `get` **pageNumber**(): `number`

**`Experimental`**

Number of the page in which the annotation is embedded.

#### Returns

`number`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`pageNumber`](../../Annotations/classes/WidgetAnnotation.md#pagenumber)

***

### privateData

> `get` **privateData**(): `object`

**`Experimental`**

Custom data to be stored with the annotation

> `set` **privateData**(`privateData`): `void`

**`Experimental`**

#### Parameters

• **privateData**: `object`

#### Returns

`object`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`privateData`](../../Annotations/classes/WidgetAnnotation.md#privatedata)

***

### renderProperties

> `get` **renderProperties**(): [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

**`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.

> `set` **renderProperties**(`v`): `void`

**`Experimental`**

#### Parameters

• **v**: [`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Returns

[`AnnotationRenderProperties`](../../Annotations/classes/AnnotationRenderProperties.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`renderProperties`](../../Annotations/classes/WidgetAnnotation.md#renderproperties)

***

### source

> `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`.

#### Returns

`void`

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`source`](../../Annotations/classes/WidgetAnnotation.md#source)

***

### type

> `get` **type**(): [`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

**`Experimental`**

The PDF annotation type

#### Default Value

`AnnotationType.Widget`

#### Returns

[`AnnotationType`](../../Annotations/enumerations/AnnotationType.md)

#### Inherited from

[`WidgetAnnotation`](../../Annotations/classes/WidgetAnnotation.md).[`type`](../../Annotations/classes/WidgetAnnotation.md#type)

---

## Forms

# Forms

## Index

### Classes

- [ButtonWidget](classes/ButtonWidget.md)
- [CheckBoxWidget](classes/CheckBoxWidget.md)
- [ComboBoxWidget](classes/ComboBoxWidget.md)
- [FormWidget](classes/FormWidget.md)
- [ListBoxWidget](classes/ListBoxWidget.md)
- [RadioButtonWidget](classes/RadioButtonWidget.md)
- [TextBoxWidget](classes/TextBoxWidget.md)

---

## Class: Inset

# Class: Inset

Inset in PDF Document

## Constructors

### new Inset()

> **new Inset**(`top`, `right`, `buttom`, `left`): [`Inset`](Inset.md)

#### Parameters

• **top**: `number`

• **right**: `number`

• **buttom**: `number`

• **left**: `number`

#### Returns

[`Inset`](Inset.md)

## Properties

### bottom

> **bottom**: `number`

***

### left

> **left**: `number`

***

### right

> **right**: `number`

***

### top

> **top**: `number`

---

## Class: Point

# Class: Point

Represents a point in a two-dimensional coordinate system.

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\

## Constructors

### new Point()

> **new Point**(`x`, `y`): [`Point`](Point.md)

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`](Point.md)

## Properties

### x

> **x**: `number`

The X value (horizontal coordinate).

***

### y

> **y**: `number`

The Y value (vertical coordinate).

## Methods

### clone()

> **clone**(): [`Point`](Point.md)

Creates a deep copy of the object.

#### Returns

[`Point`](Point.md)

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)

***

### calculateCentroid()

> `static` **calculateCentroid**(`points`): [`Point`](Point.md)

#### Parameters

• **points**: [`Point`](Point.md)[]

#### Returns

[`Point`](Point.md)

***

### calculateNormalLineYIntercept()

> `static` **calculateNormalLineYIntercept**(`point`, `normalSlope`): `number`

#### Parameters

• **point**: [`Point`](Point.md)

• **normalSlope**: `number`

#### Returns

`number`

***

### calculatePerpendicularIntersection()

> `static` **calculatePerpendicularIntersection**(`p1`, `p2`, `p3`): [`Point`](Point.md)

#### Parameters

• **p1**: [`Point`](Point.md)

• **p2**: [`Point`](Point.md)

• **p3**: [`Point`](Point.md)

#### Returns

[`Point`](Point.md)

***

### calculateSlope()

> `static` **calculateSlope**(`p1`, `p2`): `number`

#### Parameters

• **p1**: [`Point`](Point.md)

• **p2**: [`Point`](Point.md)

#### Returns

`number`

***

### calculateYIntercept()

> `static` **calculateYIntercept**(`point`, `slope`): `number`

#### Parameters

• **point**: [`Point`](Point.md)

• **slope**: `number`

#### Returns

`number`

***

### findIntersection()

> `static` **findIntersection**(`slope1`, `yIntercept1`, `slope2`, `yIntercept2`): [`Point`](Point.md)

#### Parameters

• **slope1**: `number`

• **yIntercept1**: `number`

• **slope2**: `number`

• **yIntercept2**: `number`

#### Returns

[`Point`](Point.md)

---

## Class: Quadrilateral\<T\>

# Class: Quadrilateral\

Represents a polygon with four sides and four corners.

## Type Parameters

• **T** *extends* [`Point`](Point.md)

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\\>

## Constructors

### new Quadrilateral()

> **new Quadrilateral**\(`p1`, `p2`, `p3`, `p4`): [`Quadrilateral`](Quadrilateral.md)\

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`](Quadrilateral.md)\

### new Quadrilateral()

> **new Quadrilateral**\(`x1`, `y1`, `x2`, `y2`, `x3`, `y3`, `x4`, `y4`): [`Quadrilateral`](Quadrilateral.md)\

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`](Quadrilateral.md)\

## 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` **points**(): `T`[]

#### Returns

`T`[]

## Methods

### clone()

> **clone**(): [`Quadrilateral`](Quadrilateral.md)\

Creates a deep copy of the object.

#### Returns

[`Quadrilateral`](Quadrilateral.md)\

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#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\<T\>

# Class: Rectangle\

Represents a rectangle in a two-dimensional coordinate system.

## Type Parameters

• **T** *extends* [`Point`](Point.md)

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\\>

## Constructors

### new Rectangle()

> **new Rectangle**\(`topLeft`, `size`): [`Rectangle`](Rectangle.md)\

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`](Size.md)

The size of the rectangle.

#### Returns

[`Rectangle`](Rectangle.md)\

### new Rectangle()

> **new Rectangle**\(`x`, `y`, `width`, `height`): [`Rectangle`](Rectangle.md)\

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`](Rectangle.md)\

## Properties

### size

> **size**: [`Size`](Size.md)

The size of the rectangle.

***

### topLeft

> **topLeft**: `T`

The top-left corner of the rectangle.

## Accessors

### bottomLeft

> `get` **bottomLeft**(): `T`

Gets the bottom-left corner of the rectangle.

#### Returns

`T`

***

### bottomRight

> `get` **bottomRight**(): `T`

Gets the bottom-right corner of the rectangle.

#### Returns

`T`

***

### height

> `get` **height**(): `number`

The height of the rectangle.

> `set` **height**(`height`): `void`

#### Parameters

• **height**: `number`

#### Returns

`number`

***

### topRight

> `get` **topRight**(): `T`

Gets the top-right corner of the rectangle.

#### Returns

`T`

***

### width

> `get` **width**(): `number`

The width of the rectangle.

> `set` **width**(`width`): `void`

#### Parameters

• **width**: `number`

#### Returns

`number`

## Methods

### clone()

> **clone**(): [`Rectangle`](Rectangle.md)\

Creates a deep copy of the object.

#### Returns

[`Rectangle`](Rectangle.md)\

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)

***

### calculateBoundingBox()

> `static` **calculateBoundingBox**(`points`): [`Rectangle`](Rectangle.md)\

Calculates the bounding box that encompasses a given set of points.

#### Parameters

• **points**: [`Point`](Point.md)[]

An array of [Point](Point.md) objects representing the points to enclose.

#### Returns

[`Rectangle`](Rectangle.md)\

A [Rectangle](Rectangle.md) 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](Rectangle.md) using
those boundaries.

If the input array is empty, the function returns `null`.

---

## Class: Size

# Class: Size

Represents the dimensions of an object in terms of width and height.

## Implements

- [`Cloneable`](../../../../Core/interfaces/Cloneable.md)\

## Constructors

### new Size()

> **new Size**(`width`, `height`): [`Size`](Size.md)

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`](Size.md)

## Properties

### height

> **height**: `number`

The height of the object.

***

### width

> **width**: `number`

The width of the object.

## Methods

### clone()

> **clone**(): [`Size`](Size.md)

Creates a deep copy of the object.

#### Returns

[`Size`](Size.md)

A new instance that is a deep copy of the original object.

#### Implementation of

[`Cloneable`](../../../../Core/interfaces/Cloneable.md).[`clone`](../../../../Core/interfaces/Cloneable.md#clone)

---

## Enumeration: Orientation

# 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

# Geometry

## Index

### Enumerations

- [Orientation](enumerations/Orientation.md)

### Classes

- [Inset](classes/Inset.md)
- [Point](classes/Point.md)
- [Quadrilateral](classes/Quadrilateral.md)
- [Rectangle](classes/Rectangle.md)
- [Size](classes/Size.md)

### Variables

- [PaperSize](variables/PaperSize.md)

---

## Variable: 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`](../enumerations/Orientation.md) = `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`](../enumerations/Orientation.md) = `Orientation.portrait`

### a4\_portait.width

> **width**: `number` = `123`

---

## Class: DocumentTextSearchService

# 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`](SearchService.md)\

## Constructors

### new DocumentTextSearchService()

> **new DocumentTextSearchService**(`strategy`): [`DocumentTextSearchService`](DocumentTextSearchService.md)

Constructs a new SearchService instance with the specified search strategy.

#### Parameters

• **strategy**: [`SearchStrategy`](SearchStrategy.md)\

The search strategy to be used for executing search operations.

#### Returns

[`DocumentTextSearchService`](DocumentTextSearchService.md)

#### Inherited from

[`SearchService`](SearchService.md).[`constructor`](SearchService.md#constructors)

## Properties

### strategy

> **strategy**: [`SearchStrategy`](SearchStrategy.md)\

The search strategy associated with this search service.

#### Inherited from

[`SearchService`](SearchService.md).[`strategy`](SearchService.md#strategy)

## Methods

### execute()

> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\

Executes a search operation using the specified parameters.

#### Parameters

• **params**: [`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md)

The parameters for the search operation.

#### Returns

[`SearchExecution`](SearchExecution.md)\

A SearchExecution object representing the ongoing search operation.

#### Inherited from

[`SearchService`](SearchService.md).[`execute`](SearchService.md#execute)

---

## Class: DocumentTextSearchStrategy

# 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`](SearchStrategy.md)\

## Constructors

### new DocumentTextSearchStrategy()

> **new DocumentTextSearchStrategy**(`document`): [`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)

Constructs a new `DocumentTextSearchStrategy` instance.

#### Parameters

• **document**: [`Document`](../../../classes/Document.md)

Parameter representing the PDF document to be searched.

#### Returns

[`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)

#### Overrides

[`SearchStrategy`](SearchStrategy.md).[`constructor`](SearchStrategy.md#constructors)

## Properties

### document

> **document**: [`Document`](../../../classes/Document.md)

The `Pdf.Document` instance associated with this search strategy.

#### Inherited from

[`SearchStrategy`](SearchStrategy.md).[`document`](SearchStrategy.md#document)

## Methods

### execute()

> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\

Executes the search strategy asynchronously.

#### Parameters

• **params**: [`DocumentTextSearchParams`](../interfaces/DocumentTextSearchParams.md)

The parameters for the search operation.

#### Returns

[`SearchExecution`](SearchExecution.md)\

A `SearchExecution` object representing the ongoing search operation.

#### Inherited from

[`SearchStrategy`](SearchStrategy.md).[`execute`](SearchStrategy.md#execute)

---

## Class: SearchExecution\<T\>

# Class: SearchExecution\

Event emitter for search execution events.
Extends the EventEmitter class to handle events related to search execution.

## Extends

- [`EventEmitter`](../../../../Core/classes/EventEmitter.md)\\>

## Type Parameters

• **T**

## Implements

- [`SearchExecution`](SearchExecution.md)\

## Constructors

### new SearchExecution()

> **new SearchExecution**\(): [`SearchExecution`](SearchExecution.md)\

Constructs a new `SearchExecution` instance.
Initializes the search execution with a Promise to track the search result.

#### Returns

[`SearchExecution`](SearchExecution.md)\

#### Overrides

`EventEmitter>.constructor`

## Properties

### result

> **result**: `Promise`\

A Promise representing the result of the search execution.

#### Implementation of

`SearchExecution.result`

***

### state

> **state**: [`SearchExecutionState`](../enumerations/SearchExecutionState.md) = `SearchExecutionState.Executing`

The current state of the search execution.

#### Implementation of

`SearchExecution.state`

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to listen for.

• **listener**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### 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.

#### Returns

`void`

#### Implementation of

`SearchExecution.cancel`

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to dispatch.

• **args**: `Parameters`\\[`K`\]\>

The data associated with the event.

#### Returns

`void`

#### 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.

#### Returns

`void`

#### 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.

#### Returns

`void`

#### 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.

#### Returns

`void`

#### 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.

#### Returns

`void`

#### Implementation of

`SearchExecution.onSearchStarted`

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event for which to remove all listeners.

#### Returns

`void`

#### Implementation of

`SearchExecution.removeAllListeners`

#### Inherited from

`EventEmitter.removeAllListeners`

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **K** *extends* keyof [`SearchExecutionEventMap`](../interfaces/SearchExecutionEventMap.md)\

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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Implementation of

`SearchExecution.removeEventListener`

#### Inherited from

`EventEmitter.removeEventListener`

---

## Class: SearchService\<T, K\>

# Class: SearchService\

Represents a search service that facilitates executing search operations using a specified search strategy.

## Extended by

- [`DocumentTextSearchService`](DocumentTextSearchService.md)

## Type Parameters

• **T**

The type of parameters used for the search operation.

• **K**

The type of result returned by the search operation.

## Constructors

### new SearchService()

> **new SearchService**\(`strategy`): [`SearchService`](SearchService.md)\

Constructs a new SearchService instance with the specified search strategy.

#### Parameters

• **strategy**: [`SearchStrategy`](SearchStrategy.md)\

The search strategy to be used for executing search operations.

#### Returns

[`SearchService`](SearchService.md)\

## Properties

### strategy

> **strategy**: [`SearchStrategy`](SearchStrategy.md)\

The search strategy associated with this search service.

## Methods

### execute()

> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\

Executes a search operation using the specified parameters.

#### Parameters

• **params**: `T`

The parameters for the search operation.

#### Returns

[`SearchExecution`](SearchExecution.md)\

A SearchExecution object representing the ongoing search operation.

---

## Class: `abstract` SearchStrategy\<T, K\>

# Class: `abstract` SearchStrategy\

Represents an abstract search strategy template for executing search operations.

## Extended by

- [`DocumentTextSearchStrategy`](DocumentTextSearchStrategy.md)

## Type Parameters

• **T**

The type of parameters used for the search operation.

• **K**

The type of result returned by the search operation.

## Constructors

### new SearchStrategy()

> **new SearchStrategy**\(): [`SearchStrategy`](SearchStrategy.md)\

#### Returns

[`SearchStrategy`](SearchStrategy.md)\

## Properties

### document

> **document**: [`Document`](../../../classes/Document.md)

The `Pdf.Document` instance associated with this search strategy.

## Methods

### execute()

> **execute**(`params`): [`SearchExecution`](SearchExecution.md)\

Executes the search strategy asynchronously.

#### Parameters

• **params**: `T`

The parameters for the search operation.

#### Returns

[`SearchExecution`](SearchExecution.md)\

A `SearchExecution` object representing the ongoing search operation.

---

## Enumeration: SearchExecutionState

# 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

# Search

## Index

### Enumerations

- [SearchExecutionState](enumerations/SearchExecutionState.md)

### Classes

- [DocumentTextSearchService](classes/DocumentTextSearchService.md)
- [DocumentTextSearchStrategy](classes/DocumentTextSearchStrategy.md)
- [SearchExecution](classes/SearchExecution.md)
- [SearchService](classes/SearchService.md)
- [SearchStrategy](classes/SearchStrategy.md)

### Interfaces

- [DocumentTextSearchParams](interfaces/DocumentTextSearchParams.md)
- [DocumentTextSearchResult](interfaces/DocumentTextSearchResult.md)
- [DocumentTextSearchResultContextInfo](interfaces/DocumentTextSearchResultContextInfo.md)
- [SearchExecutionEventMap](interfaces/SearchExecutionEventMap.md)

---

## Interface: DocumentTextSearchParams

# 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

# 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`](DocumentTextSearchResultContextInfo.md)

The context info containing text that surrounds matched text.

***

### pageNumber

> **pageNumber**: `number`

The page number where the text was found.

***

### quadrilaterals

> **quadrilaterals**: [`Quadrilateral`](../../Geometry/classes/Quadrilateral.md)\[]

Quadrilaterals outlining the position of the text on the page.

***

### text

> **text**: `string`

The matched text found during the search.

---

## Interface: DocumentTextSearchResultContextInfo

# 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\<T\>

# Interface: SearchExecutionEventMap\

Interface defining event types for `SearchExecution`.
Specifies the types of events that can be emitted during a search execution.

## Type Parameters

• **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.

#### Returns

`void`

***

### searchCanceled()

> **searchCanceled**: () => `void`

Event triggered when the search execution is canceled.

#### Returns

`void`

***

### searchFinished()

> **searchFinished**: (`result`) => `void`

Event triggered when the search execution finishes.

#### Parameters

• **result**: `T`

The result of the search execution.

#### Returns

`void`

***

### searchResultsFound()

> **searchResultsFound**: (`result`) => `void`

Event triggered when search results are found.

#### Parameters

• **result**: `T`

The result of the search execution.

#### Returns

`void`

***

### searchStarted()

> **searchStarted**: (`result`) => `void`

Event triggered when the search execution starts.

#### Parameters

• **result**: `T`

The result of the search execution.

#### Returns

`void`

---

## Class: AccessibilityLayer

# 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`](Layer.md)\

## Constructors

### new AccessibilityLayer()

> **new AccessibilityLayer**(`id`, `documentViewPage`): [`AccessibilityLayer`](AccessibilityLayer.md)

Creates an instance of Layer.

#### Parameters

• **id**: `string`

The unique identifier for the layer.

• **documentViewPage**: `DocumentViewPage`

The associated document view page.

#### Returns

[`AccessibilityLayer`](AccessibilityLayer.md)

#### Inherited from

[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)

## Accessors

### documentViewPage

> `get` **documentViewPage**(): `DocumentViewPage`

Gets the document view page associated with this layer.

#### Returns

`DocumentViewPage`

#### Inherited from

[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)

***

### id

> `get` **id**(): `string`

Gets the unique identifier of the layer.

#### Returns

`string`

#### Inherited from

[`Layer`](Layer.md).[`id`](Layer.md#id)

***

### nativeElement

> `get` **nativeElement**(): `T`

Gets the native HTML element of this layer.

#### Returns

`T`

#### Inherited from

[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)

***

### size

> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

Gets the size of the layer.

> `set` **size**(`v`): `void`

Sets the size of the layer and dispatches a size change event if the size is different.

#### Parameters

• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size to be set.

#### Returns

[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

#### Inherited from

[`Layer`](Layer.md).[`size`](Layer.md#size)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)

---

## Class: DocumentView

# Class: DocumentView

Class for managing the presentation and interaction with a PDF document within a container element.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Implements

- [`Disposable`](../../Core/interfaces/Disposable.md)

## Constructors

### new DocumentView()

> **new DocumentView**(`container`, `options`?): [`DocumentView`](DocumentView.md)

Constructor for the DocumentView class.

#### Parameters

• **container**: `HTMLElement`

The container element in which the document view will be displayed.

• **options?**: [`DocumentViewOptions`](../type-aliases/DocumentViewOptions.md)

#### Returns

[`DocumentView`](DocumentView.md)

#### Overrides

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)

## Properties

### DEFAULT\_DPI

> `readonly` `static` **DEFAULT\_DPI**: `number`

## Accessors

### accessibilityLayerEnabled

> `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.

> `set` **accessibilityLayerEnabled**(`v`): `void`

#### Parameters

• **v**: `boolean`

#### Returns

`boolean`

***

### currentPageNumber

> `get` **currentPageNumber**(): `number`

Gets or sets the currently most visible page.

> `set` **currentPageNumber**(`pageNumber`): `void`

#### Parameters

• **pageNumber**: `number`

#### 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.

***

### dpi

> `get` **dpi**(): `number`

Gets the `dpi` (Dots Per Inch) value which influences the rendering resolution of a document view.
Higher DPI values result in higher resolution images, which can make them appear sharper and more detailed.

#### Default

```ts
window.devicePixelRatio * 96
```

#### Returns

`number`

***

### firstVisiblePageNumber

> `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` **fitMode**(): [`FitMode`](../../Pdf/enumerations/FitMode.md)

**`Experimental`**

Gets or sets the fit mode for the document view.

> `set` **fitMode**(`fitMode`): `void`

#### Parameters

• **fitMode**: [`FitMode`](../../Pdf/enumerations/FitMode.md)

#### Returns

[`FitMode`](../../Pdf/enumerations/FitMode.md)

***

### lastVisiblePageNumber

> `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` **pageLayoutMode**(): [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)

**`Experimental`**

Gets or sets the page layout mode for the document view.

> `set` **pageLayoutMode**(`pageLayoutMode`): `void`

#### Parameters

• **pageLayoutMode**: [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)

#### Returns

[`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)

***

### pdfDocument

> `get` **pdfDocument**(): [`Document`](../../Pdf/classes/Document.md)

Gets `Pdf.Document` attached to the `DocumentView`.

#### Returns

[`Document`](../../Pdf/classes/Document.md)

***

### rotation

> `get` **rotation**(): [`Rotation`](../../Pdf/enumerations/Rotation.md)

**`Experimental`**

Gets or sets the rotation for the document view.

> `set` **rotation**(`rotation`): `void`

#### Parameters

• **rotation**: [`Rotation`](../../Pdf/enumerations/Rotation.md)

#### Returns

[`Rotation`](../../Pdf/enumerations/Rotation.md)

***

### scrollAllowance

> `get` **scrollAllowance**(): `ScrollAllowance`

Get the current scroll allowances

#### Returns

`ScrollAllowance`

***

### scrollContainer

> `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` **slidingWindow**(): `Map`\

Gets pages in sliding window.

#### Returns

`Map`\

***

### viewport

> `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` **zoom**(): `number`

Gets or sets the currently used zoom factor as a floating-point number.
1 corresponds to a zoom level of 100%.

> `set` **zoom**(`zoom`): `void`

#### Parameters

• **zoom**: `number`

#### Returns

`number`

Zoom level or null if the document view is not initialized.

***

### zoomLevels

> `get` **zoomLevels**(): `number`[]

Gets or sets the array of zoom levels available for the document view.

> `set` **zoomLevels**(`zoomLevels`): `void`

#### Parameters

• **zoomLevels**: `number`[]

#### Returns

`number`[]

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to listen for.

• **listener**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to dispatch.

• **args**: `Parameters`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#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.

#### Returns

`void`

#### Implementation of

[`Disposable`](../../Core/interfaces/Disposable.md).[`dispose`](../../Core/interfaces/Disposable.md#dispose)

***

### goToDestination()

> **goToDestination**(`destination`): `any`

Navigates to the specified destination in the document view.

#### Parameters

• **destination**: [`Destination`](../../Pdf/namespaces/Destination/interfaces/Destination.md)

The destination to navigate to.

#### Returns

`any`

***

### 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`](../../Pdf/classes/Document.md)

The PDF document which will be displayed inside the document view.

#### Returns

`void`

***

### 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**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event for which to remove all listeners.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **K** *extends* keyof [`DocumentViewEventMap`](../interfaces/DocumentViewEventMap.md)

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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

---

## Class: `abstract` Layer\<T\>

# Class: `abstract` Layer\

Abstract base class for a Layer, which is an event emitter that renders on a native HTML element.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Extended by

- [`PageImageLayer`](PageImageLayer.md)
- [`SearchResultsLayer`](SearchResultsLayer.md)
- [`AccessibilityLayer`](AccessibilityLayer.md)
- [`TextSelectionLayer`](TextSelectionLayer.md)

## Type Parameters

• **T** *extends* [`LayerNativeElementType`](../type-aliases/LayerNativeElementType.md)

The type of the native element, either `HTMLDivElement` or `HTMLCanvasElement`.

## Constructors

### new Layer()

> **new Layer**\(`id`, `documentViewPage`): [`Layer`](Layer.md)\

Creates an instance of Layer.

#### Parameters

• **id**: `string`

The unique identifier for the layer.

• **documentViewPage**: `DocumentViewPage`

The associated document view page.

#### Returns

[`Layer`](Layer.md)\

#### Overrides

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)

## Accessors

### documentViewPage

> `get` **documentViewPage**(): `DocumentViewPage`

Gets the document view page associated with this layer.

#### Returns

`DocumentViewPage`

***

### id

> `get` **id**(): `string`

Gets the unique identifier of the layer.

#### Returns

`string`

***

### nativeElement

> `get` **nativeElement**(): `T`

Gets the native HTML element of this layer.

#### Returns

`T`

***

### size

> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

Gets the size of the layer.

> `set` **size**(`v`): `void`

Sets the size of the layer and dispatches a size change event if the size is different.

#### Parameters

• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size to be set.

#### Returns

[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

---

## Class: PageImageLayer

# Class: PageImageLayer

Represents a layer that renders an page image on a canvas.

## Extends

- [`Layer`](Layer.md)\

## Constructors

### new PageImageLayer()

> **new PageImageLayer**(`id`, `documentViewPage`): [`PageImageLayer`](PageImageLayer.md)

Creates an instance of Layer.

#### Parameters

• **id**: `string`

The unique identifier for the layer.

• **documentViewPage**: `DocumentViewPage`

The associated document view page.

#### Returns

[`PageImageLayer`](PageImageLayer.md)

#### Inherited from

[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)

## Accessors

### documentViewPage

> `get` **documentViewPage**(): `DocumentViewPage`

Gets the document view page associated with this layer.

#### Returns

`DocumentViewPage`

#### Inherited from

[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)

***

### id

> `get` **id**(): `string`

Gets the unique identifier of the layer.

#### Returns

`string`

#### Inherited from

[`Layer`](Layer.md).[`id`](Layer.md#id)

***

### image

> `set` **image**(`v`): `void`

Sets the page image data and triggers rendering.

#### Parameters

• **v**: [`Image`](../interfaces/Image.md)

The new image data.

***

### nativeElement

> `get` **nativeElement**(): `T`

Gets the native HTML element of this layer.

#### Returns

`T`

#### Inherited from

[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)

***

### size

> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

Gets the size of the layer.

> `set` **size**(`v`): `void`

Sets the size of the layer and dispatches a size change event if the size is different.

#### Parameters

• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size to be set.

#### Returns

[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

#### Inherited from

[`Layer`](Layer.md).[`size`](Layer.md#size)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)

---

## Class: PluginManager

# Class: PluginManager

Manages a collection of plugins, allowing registration, activation, and deactivation.

## Constructors

### new PluginManager()

> **new PluginManager**(): [`PluginManager`](PluginManager.md)

#### Returns

[`PluginManager`](PluginManager.md)

## Accessors

### documentView

> `get` **documentView**(): [`DocumentView`](DocumentView.md)

Gets the current document view.

> `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`](DocumentView.md)

#### Returns

[`DocumentView`](DocumentView.md)

## Methods

### activatePlugin()

> **activatePlugin**(`plugin`): `void`

Activates a given plugin and deactivates all other plugins.

#### Parameters

• **plugin**: [`Plugin`](../interfaces/Plugin.md)

The plugin to activate.

#### Returns

`void`

***

### 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.

#### Returns

`void`

#### Throws

If the plugin with the given ID does not exist.

***

### deregisterPlugin()

> **deregisterPlugin**(`plugin`): `void`

Deregisters a plugin and deactivates it.

#### Parameters

• **plugin**: [`Plugin`](../interfaces/Plugin.md)

The plugin to deregister.

#### Returns

`void`

***

### deregisterPluginById()

> **deregisterPluginById**(`pluginId`): `void`

Deregisters a plugin by its ID.

#### Parameters

• **pluginId**: `string`

The ID of the plugin to deregister.

#### Returns

`void`

#### Throws

If the plugin with the given ID does not exist.

***

### getPluginById()

> **getPluginById**(`id`): [`Plugin`](../interfaces/Plugin.md)

Retrieves a plugin by its ID.

#### Parameters

• **id**: `string`

The ID of the plugin to retrieve.

#### Returns

[`Plugin`](../interfaces/Plugin.md)

The plugin with the given ID, or undefined if not found.

***

### registerPlugin()

> **registerPlugin**(`plugin`): `void`

Registers a new plugin.

#### Parameters

• **plugin**: [`Plugin`](../interfaces/Plugin.md)

The plugin to register.

#### Returns

`void`

#### Throws

If a plugin with the same ID is already registered.

---

## Class: SearchResultsLayer

# Class: SearchResultsLayer

Represents a layer that highlights search results on a PDF document.

## Extends

- [`Layer`](Layer.md)\

## Constructors

### new SearchResultsLayer()

> **new SearchResultsLayer**(`id`, `documentViewPage`): [`SearchResultsLayer`](SearchResultsLayer.md)

Creates an instance of Layer.

#### Parameters

• **id**: `string`

The unique identifier for the layer.

• **documentViewPage**: `DocumentViewPage`

The associated document view page.

#### Returns

[`SearchResultsLayer`](SearchResultsLayer.md)

#### Inherited from

[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)

## Accessors

### activeSearchResult

> `set` **activeSearchResult**(`v`): `void`

Sets the active search result and triggers rendering.

#### Parameters

• **v**: [`DocumentTextSearchResult`](../../Pdf/namespaces/Search/interfaces/DocumentTextSearchResult.md)

The active search result.

***

### documentViewPage

> `get` **documentViewPage**(): `DocumentViewPage`

Gets the document view page associated with this layer.

#### Returns

`DocumentViewPage`

#### Inherited from

[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)

***

### id

> `get` **id**(): `string`

Gets the unique identifier of the layer.

#### Returns

`string`

#### Inherited from

[`Layer`](Layer.md).[`id`](Layer.md#id)

***

### nativeElement

> `get` **nativeElement**(): `T`

Gets the native HTML element of this layer.

#### Returns

`T`

#### Inherited from

[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)

***

### searchResults

> `set` **searchResults**(`v`): `void`

Sets the search results and triggers rendering.

#### Parameters

• **v**: [`DocumentTextSearchResult`](../../Pdf/namespaces/Search/interfaces/DocumentTextSearchResult.md)[]

The new search results.

***

### size

> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

Gets the size of the layer.

> `set` **size**(`v`): `void`

Sets the size of the layer and dispatches a size change event if the size is different.

#### Parameters

• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size to be set.

#### Returns

[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

#### Inherited from

[`Layer`](Layer.md).[`size`](Layer.md#size)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)

---

## Class: TextSelectionLayer

# Class: TextSelectionLayer

Abstract base class for a Layer, which is an event emitter that renders on a native HTML element.

## Extends

- [`Layer`](Layer.md)\

## Constructors

### new TextSelectionLayer()

> **new TextSelectionLayer**(`id`, `documentViewPage`): [`TextSelectionLayer`](TextSelectionLayer.md)

Creates an instance of Layer.

#### Parameters

• **id**: `string`

The unique identifier for the layer.

• **documentViewPage**: `DocumentViewPage`

The associated document view page.

#### Returns

[`TextSelectionLayer`](TextSelectionLayer.md)

#### Inherited from

[`Layer`](Layer.md).[`constructor`](Layer.md#constructors)

## Accessors

### documentViewPage

> `get` **documentViewPage**(): `DocumentViewPage`

Gets the document view page associated with this layer.

#### Returns

`DocumentViewPage`

#### Inherited from

[`Layer`](Layer.md).[`documentViewPage`](Layer.md#documentviewpage)

***

### id

> `get` **id**(): `string`

Gets the unique identifier of the layer.

#### Returns

`string`

#### Inherited from

[`Layer`](Layer.md).[`id`](Layer.md#id)

***

### nativeElement

> `get` **nativeElement**(): `T`

Gets the native HTML element of this layer.

#### Returns

`T`

#### Inherited from

[`Layer`](Layer.md).[`nativeElement`](Layer.md#nativeelement)

***

### size

> `get` **size**(): [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

Gets the size of the layer.

> `set` **size**(`v`): `void`

Sets the size of the layer and dispatches a size change event if the size is different.

#### Parameters

• **v**: [`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size to be set.

#### Returns

[`Size`](../../Pdf/namespaces/Geometry/classes/Size.md)

#### Inherited from

[`Layer`](Layer.md).[`size`](Layer.md#size)

## Methods

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **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**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`addEventListener`](Layer.md#addeventlistener)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **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`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`dispatchEvent`](Layer.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **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.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeAllListeners`](Layer.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`Layer`](Layer.md).[`removeEventListener`](Layer.md#removeeventlistener)

---

## Class: TextSelectionPlugin

# Class: TextSelectionPlugin

Represents a plugin that can be registered, activated, and deactivated.

## Extends

- [`EventEmitter`](../../Core/classes/EventEmitter.md)\

## Implements

- [`Plugin`](../interfaces/Plugin.md)

## Constructors

### new TextSelectionPlugin()

> **new TextSelectionPlugin**(`documentView`): [`TextSelectionPlugin`](TextSelectionPlugin.md)

#### Parameters

• **documentView**: [`DocumentView`](DocumentView.md)

#### Returns

[`TextSelectionPlugin`](TextSelectionPlugin.md)

#### Overrides

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`constructor`](../../Core/classes/EventEmitter.md#constructors)

## Properties

### id

> **id**: `string` = `'text-selection-plugin'`

Unique identifier for the plugin.

#### Implementation of

[`Plugin`](../interfaces/Plugin.md).[`id`](../interfaces/Plugin.md#id)

## Accessors

### active

> `get` **active**(): `boolean`

> `set` **active**(`v`): `void`

#### Parameters

• **v**: `boolean`

#### Returns

`boolean`

***

### debugMode

> `get` **debugMode**(): `boolean`

> `set` **debugMode**(`v`): `void`

#### Parameters

• **v**: `boolean`

#### Returns

`boolean`

***

### documentView

> `get` **documentView**(): [`DocumentView`](DocumentView.md)

The document view associated with the plugin.

> `set` **documentView**(`v`): `void`

The document view associated with the plugin.

#### Parameters

• **v**: [`DocumentView`](DocumentView.md)

#### Returns

[`DocumentView`](DocumentView.md)

The document view associated with the plugin.

#### Implementation of

[`Plugin`](../interfaces/Plugin.md).[`documentView`](../interfaces/Plugin.md#documentview)

## Methods

### activate()

> **activate**(): `void`

Activates the plugin.

#### Returns

`void`

#### Implementation of

[`Plugin`](../interfaces/Plugin.md).[`activate`](../interfaces/Plugin.md#activate)

***

### addEventListener()

> **addEventListener**\(`type`, `listener`): `void`

Register a function that will be called whenever the specified event is delivered.

#### Type Parameters

• **K** *extends* `"textSelectionChanged"`

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to listen for.

• **listener**

The function that will be executed when an event of the specified type occurs.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`addEventListener`](../../Core/classes/EventEmitter.md#addeventlistener)

***

### deactivate()

> **deactivate**(): `void`

Deactivates the plugin.

#### Returns

`void`

#### Implementation of

[`Plugin`](../interfaces/Plugin.md).[`deactivate`](../interfaces/Plugin.md#deactivate)

***

### dispatchEvent()

> **dispatchEvent**\(`type`, `args`): `void`

Dispatches an event to all registered listeners.

#### Type Parameters

• **K** *extends* `"textSelectionChanged"`

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event type to dispatch.

• **args**: `Parameters`\

The data associated with the event.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`dispatchEvent`](../../Core/classes/EventEmitter.md#dispatchevent)

***

### removeAllListeners()

> **removeAllListeners**\(`type`): `void`

Remove all listeners for a given event.

#### Type Parameters

• **K** *extends* `"textSelectionChanged"`

A generic type representing the key of the event type.

#### Parameters

• **type**: `K`

String representing the event for which to remove all listeners.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeAllListeners`](../../Core/classes/EventEmitter.md#removealllisteners)

***

### removeEventListener()

> **removeEventListener**\(`type`, `listener`): `void`

Removes an event listener previously registered with addEventListener.

#### Type Parameters

• **K** *extends* `"textSelectionChanged"`

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**

The event listener function of the event handler to remove from the event target.

#### Returns

`void`

#### Inherited from

[`EventEmitter`](../../Core/classes/EventEmitter.md).[`removeEventListener`](../../Core/classes/EventEmitter.md#removeeventlistener)

---

## Function: drawTextSelectionInfo()

# Function: drawTextSelectionInfo()

> **drawTextSelectionInfo**(`documentView`, `textSelectionInfo`, `debugMode`): `void`

## Parameters

• **documentView**: [`DocumentView`](../classes/DocumentView.md)

• **textSelectionInfo**: `TextSelectionInfo`

• **debugMode**: `boolean` = `false`

## Returns

`void`

---

## Function: drawTextSelectionInfoDebug()

# Function: drawTextSelectionInfoDebug()

> **drawTextSelectionInfoDebug**(`documentView`, `textSelectionInfo`): `void`

## Parameters

• **documentView**: [`DocumentView`](../classes/DocumentView.md)

• **textSelectionInfo**: `TextSelectionInfo`

## Returns

`void`

---

## UI

# UI

## Index

### Classes

- [AccessibilityLayer](classes/AccessibilityLayer.md)
- [DocumentView](classes/DocumentView.md)
- [Layer](classes/Layer.md)
- [PageImageLayer](classes/PageImageLayer.md)
- [PluginManager](classes/PluginManager.md)
- [SearchResultsLayer](classes/SearchResultsLayer.md)
- [TextSelectionLayer](classes/TextSelectionLayer.md)
- [TextSelectionPlugin](classes/TextSelectionPlugin.md)

### Interfaces

- [DocumentViewEventMap](interfaces/DocumentViewEventMap.md)
- [Image](interfaces/Image.md)
- [LayerEventMap](interfaces/LayerEventMap.md)
- [Plugin](interfaces/Plugin.md)
- [TextSelectionPluginEventMap](interfaces/TextSelectionPluginEventMap.md)

### Type Aliases

- [DocumentViewOptions](type-aliases/DocumentViewOptions.md)
- [LayerNativeElementType](type-aliases/LayerNativeElementType.md)

### Functions

- [drawTextSelectionInfo](functions/drawTextSelectionInfo.md)
- [drawTextSelectionInfoDebug](functions/drawTextSelectionInfoDebug.md)

---

## Interface: DocumentViewEventMap

# 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`

#### Returns

`void`

***

### documentViewClick()

> **documentViewClick**: (`payload`) => `void`

Event triggered when the document view is clicked.
The event payload is the MouseEvent object.

#### Parameters

• **payload**: `MouseEvent`

#### Returns

`void`

***

### documentViewDoubleClick()

> **documentViewDoubleClick**: (`payload`) => `void`

Event triggered when the document view is double-clicked.
The event payload is the MouseEvent object.

#### Parameters

• **payload**: `MouseEvent`

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### documentViewMouseEnter()

> **documentViewMouseEnter**: (`payload`) => `void`

Event triggered when the mouse enters the document view.
The event payload is the MouseEvent object.

#### Parameters

• **payload**: `MouseEvent`

#### Returns

`void`

***

### documentViewMouseLeave()

> **documentViewMouseLeave**: (`payload`) => `void`

Event triggered when the mouse leaves the document view.
The event payload is the MouseEvent object.

#### Parameters

• **payload**: `MouseEvent`

#### Returns

`void`

***

### documentViewMouseMove()

> **documentViewMouseMove**: (`payload`) => `void`

Event triggered when the mouse moves within the document view.
The event payload is the MouseEvent object.

#### Parameters

• **payload**: `MouseEvent`

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### documentViewPointerCancel()

> **documentViewPointerCancel**: (`event`) => `void`

Fired when a pointer is canceled (e.g. touch→pointercancel) in the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### documentViewPointerDown()

> **documentViewPointerDown**: (`event`) => `void`

Fired when a pointer is pressed down anywhere in the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### documentViewPointerEnter()

> **documentViewPointerEnter**: (`event`) => `void`

Fired when a pointer enters the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### documentViewPointerLeave()

> **documentViewPointerLeave**: (`event`) => `void`

Fired when a pointer leaves the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### documentViewPointerMove()

> **documentViewPointerMove**: (`event`) => `void`

Fired when a pointer moves within the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### documentViewPointerUp()

> **documentViewPointerUp**: (`event`) => `void`

Fired when a pointer is released anywhere in the document view.

#### Parameters

• **event**: `PointerEvent`

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### documentViewTouchEnd()

> **documentViewTouchEnd**: (`payload`) => `void`

Event triggered when a touch ends within the document view.
The event payload is the TouchEvent object.

#### Parameters

• **payload**: `TouchEvent`

#### Returns

`void`

***

### documentViewTouchMove()

> **documentViewTouchMove**: (`payload`) => `void`

Event triggered when a touch moves within the document view.
The event payload is the TouchEvent object.

#### Parameters

• **payload**: `TouchEvent`

#### Returns

`void`

***

### documentViewTouchStart()

> **documentViewTouchStart**: (`payload`) => `void`

Event triggered when a touch starts within the document view.
The event payload is the TouchEvent object.

#### Parameters

• **payload**: `TouchEvent`

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### 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`](../../Pdf/enumerations/FitMode.md)

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### pageAddedToViewport()

> **pageAddedToViewport**: (`pageNumber`) => `void`

#### Parameters

• **pageNumber**: `number`

#### Returns

`void`

***

### pageClick()

> **pageClick**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pageDoubleClick()

> **pageDoubleClick**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### 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`](../../Pdf/enumerations/PageLayoutMode.md)

#### Returns

`void`

***

### pageMouseDown()

> **pageMouseDown**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pageMouseEnter()

> **pageMouseEnter**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pageMouseLeave()

> **pageMouseLeave**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pageMouseMove()

> **pageMouseMove**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pageMouseUp()

> **pageMouseUp**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `MouseEvent`

#### Returns

`void`

***

### pagePointerCancel()

> **pagePointerCancel**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pagePointerDown()

> **pagePointerDown**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pagePointerEnter()

> **pagePointerEnter**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pagePointerLeave()

> **pagePointerLeave**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pagePointerMove()

> **pagePointerMove**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pagePointerUp()

> **pagePointerUp**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `PointerEvent`

#### Returns

`void`

***

### pageRemovedFromViewport()

> **pageRemovedFromViewport**: (`pageNumber`) => `void`

#### Parameters

• **pageNumber**: `number`

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### pageTouchCancel()

> **pageTouchCancel**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `TouchEvent`

#### Returns

`void`

***

### pageTouchEnd()

> **pageTouchEnd**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `TouchEvent`

#### Returns

`void`

***

### pageTouchMove()

> **pageTouchMove**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `TouchEvent`

#### Returns

`void`

***

### pageTouchStart()

> **pageTouchStart**: (`pageNumber`, `payload`) => `void`

#### Parameters

• **pageNumber**: `number`

• **payload**: `TouchEvent`

#### Returns

`void`

***

### 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`](../../Pdf/enumerations/Rotation.md)

#### Returns

`void`

***

### 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`

#### Returns

`void`

***

### 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: Image

Interface representing the image provided by the PDF renderer.

## Properties

### buffer

> **buffer**: `ArrayBuffer`

***

### height

> **height**: `number`

***

### width

> **width**: `number`

---

## Interface: LayerEventMap

# 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`](../../Pdf/namespaces/Geometry/classes/Size.md)

The new size of the layer.

#### Returns

`void`

---

## Interface: Plugin

# Interface: Plugin

Represents a plugin that can be registered, activated, and deactivated.

## Properties

### documentView

> **documentView**: [`DocumentView`](../classes/DocumentView.md)

The document view associated with the plugin.

***

### id

> **id**: `string`

Unique identifier for the plugin.

## Methods

### activate()

> **activate**(): `void`

Activates the plugin.

#### Returns

`void`

***

### deactivate()

> **deactivate**(): `void`

Deactivates the plugin.

#### Returns

`void`

---

## Interface: TextSelectionPluginEventMap

# Interface: TextSelectionPluginEventMap

Interface defining event types for changes in a document view.

## Properties

### textSelectionChanged()

> **textSelectionChanged**: (`selectedText`) => `void`

#### Parameters

• **selectedText**: `string`

#### Returns

`void`

---

## Type Alias: DocumentViewOptions

# 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.

## Type declaration

### 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

```ts
false
```

### dpi?

> `optional` **dpi**: `number`

Specifies the DPI (Dots Per Inch) value for rendering the document.
Higher DPI values result in higher resolution images, making them appear sharper and more detailed.

#### Default

```ts
96
```

### fitMode?

> `optional` **fitMode**: [`FitMode`](../../Pdf/enumerations/FitMode.md)

Specifies the fit mode for the document view.
Determines how the document pages are scaled to fit within the viewport.

#### Default

```ts
FitMode.None
```

### pageLayoutMode?

> `optional` **pageLayoutMode**: [`PageLayoutMode`](../../Pdf/enumerations/PageLayoutMode.md)

Specifies the page layout mode for the document view.
Determines how pages are arranged within the viewport (e.g., single column, two columns).

#### Default

```ts
PageLayoutMode.OneColumn
```

---

## Type Alias: LayerNativeElementType

# Type Alias: LayerNativeElementType

> **LayerNativeElementType**: `HTMLDivElement` \| `HTMLCanvasElement`

Represents the native element types that a Layer can use.

---

## Type Alias: LicenseKey

# Type Alias: LicenseKey

> **LicenseKey**: \`\\`

---

## Variable: pdfToolsWebSdk

# Variable: pdfToolsWebSdk

> `const` **pdfToolsWebSdk**: `PdfToolsWebSdk`

---

## Customize the PDF Viewer SDK

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-778 */}

---

## Getting started with the PDF Viewer SDK

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Get up and running with the PDF Viewer SDK.

This guide walks you through the steps to integrate the [the ready-to-use viewer](../README.mdx#pdf-web-sdk) 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

1. Download or clone the [sample repository](https://github.com/pdf-tools/pdf-web-viewer-samples/tree/main).
1. From the root of the repository, navigate to a sample at:

    ```
    examples/vanilla-typescript/view-pdf
    ```

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 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/main).
:::

## 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-sdk/dist/wasm` sub-directory. To allow proper initialization of the PDF Web Viewer inside of your application, make mentioned files publicly available to the application from a base path (for example: `/pdftools-viewer-sdk`). 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.

In React, tools like **Webpack** or **Rollup** are typically used for bundling your application.

    
  

  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).

  
  

  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).

  
  

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).

In Vue, **Webpack** is typically used for bundling your application.

    
  

  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).

Tools like **Webpack** or **Rollup** can be used for bundling your application. 

    
  

  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).

  
  

  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](../README.mdx#pdf-web-sdk) without the [PDF Web Viewer](../README.mdx#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
      
      
        
        
      
    
    ```

1. Create a short TypeScript file that performs the initiliazation of the PDF Viewer SDK:

    ```typescript
    import { PdfToolsViewer } from '../../components/pdftools-viewer';

    // create the viewer element
    const el = PdfToolsViewer.initialize();
    // attach it to the reserved element
    const container = document.getElementById('viewer-container');
    container.append(el);
    ```

:::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 el = PdfToolsViewer.init({
    path: './pdftools-web-viewer/',
  });
```
:::

### Manage license key

The PDF Viewer SDK displays watermarked pages by default. Use a license key to remove the watermark for free. 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. Find the `PdfToolsViewer.init` in the `index.ts` or `index.js`, and include the license key as follows:

    ```ts
    const el = await PdfToolsViewer.init({licenseKey: ""});
    ```

### 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:

```typescript
// open a document from a URL
PdfToolsViewerApi.document.openFromUrl('../pdf/WebViewer_Demo.pdf');
```

```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: 'text/plain',
});

// open the file
PdfToolsViewerApi.document.openFromFile(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 an in memory array
const uint8array = new Uint8Array(arrayBuffer);

// open the in memory arry
PdfToolsViewerApi.document.openFromMemory(uint8array);
```

### Implement your use case

- Find instructions how to implement specific use cases in the [guides](../guides/README.mdx) section.
- Find more technical information about the PDF Viewer SDK in the [API references](../api-references/README.mdx).
{/*- Play with the PDF Viewer SDK in the [playground](TODO). */}

:::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 sifnificant development effort than the full PDF Viewer SDK. For more details, review the following sections and pages: 
- [PDF Web SDK](../README.mdx#pdf-web-sdk)
- [Advanced functionality](../guides/README.mdx)
:::

---

## Custom implementation guides

import DocCardList from '@theme/DocCardList';

:::info
These guides focus on the advanced functionality of the [PDF Web SDK](../README.mdx#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](../getting-started/README.mdx).

Refer to the API references for more information about the differences between PDF Viewer SDK and PDF Web SDK. [API references](../api-references/README.mdx).
:::

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

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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)

---

:::note Before you begin
Learn how to [get started](../getting-started/README.mdx) and [make static assets available](../getting-started/README.mdx#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`](../api-references/web-sdk/namespaces/Pdf/classes/AnnotationManager.md) 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 losely 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 flexibilty 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 flexibilty 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 continously add, update, and delete annotations in document.

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-780 make this a codesandbox sample */}

```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;
  setTimeout(() => {
    // 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 annotations reaches end of the page -> delete it
    const lastAnnotation = annotationsUpdated[annotationsUpdated.length-1];
    if(lastAnnotation.boundingBox.topLeft.x > 500)
    {
      pdfDocument.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++;
      pdfDocument.add(new Pdf.Annotations.FreeTextAnnotation({
        page: doc.pages.getByNumber(1),
        boundingBox: new Pdf.Geometry.Rectangle(10, 100, 50, 50),
        content: `Annotation #${annotationCounter}`,
        author: 'John Doe',
        subject: `Subject #${annotationCounter}`,
      }));
    }
  }, 100);
});
```

---

## Read PDF information

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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)

---

:::note Before you begin
Learn how to [get started](../getting-started/README.mdx) and [make static assets available](../getting-started/README.mdx#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](../api-references/web-sdk/namespaces/Pdf/classes/Document.md) and [Pdf.Metadata](../api-references/web-sdk/namespaces/Pdf/classes/Metadata.md).
:::

## Full example

This full sample demonstrates how to open a document and log document information to the console.

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-780 make this a codesandbox sample */}

```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

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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)

---

:::note Before you begin
Navigating within a PDF document requires a `DocumentView`. 
Learn how to [view a document](./document-view.mdx).
:::

## 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
pdfDocument.goToPage(5);

// go to next page
pdfDocument.nextPage();

// go to previous page
pdfDocument.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.

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-780 make this a codesandbox sample */}

```typescript
import { pdfToolsWebSdk, Pdf } from '@pdftools/pdf-web-sdk';

pdfToolsWebSdk.initialize().then(async () => {    
  // create document view
  const container = document.querySelector('#pdftools-web-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];
    pdfDocument.goToPage(firstAnnotation.page.pageNumber);
  }
});
```

---

## Search text in PDF

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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)

---

:::note Before you begin
Learn how to [get started](../getting-started/README.mdx) and [make static assets available](../getting-started/README.mdx#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 derived from `SearchStragey` 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({
    'pdf', // query
    false, // caseSensitive
    false, // regularExpression
});

// 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](./event-emitter.mdx).
:::

## Full example

This full sample demonstrates how to configure and execute a search, and log search results to the console.

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-780 make this a codesandbox sample */}

```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({
      'pdf', // query
      false, // caseSensitive
      false, // regularExpression
  });

  // 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

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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)

---

:::note Before you begin
Learn how to [get started](../getting-started/README.mdx) and [make static assets available](../getting-started/README.mdx#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-web-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 = new Pdf.Controller();
```

## 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.

{/* TODO https://smallpdf.atlassian.net/browse/PDFTVIEWER-780 make this a codesandbox sample */}

** 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-web-viewer-container');
  const documentView = new UI.DocumentView(container);

  const controller = new Pdf.Controller();
  const pdfDocument = await controller.openDocument({
    uri: '/pdf/WebViewer_Demo.pdf',
  });

  documentView.initialize(pdfDocument);
}

initialize();
```

---

## Manage events

:::info
In this documentation, you can learn how to implement specific features of the PDF Web 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](../getting-started/README.mdx).
:::

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 typesafe 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)

---
:::note Before you begin
The `EventEmitter` class can be used noth within or outside of the context of the PDF Viewer SDK. 
However, if you want to listen to events emitted by or dispatch events to the PDF Viewer SDK, first learn how to work with the PDF Web SDK, for example how to [view a document](./document-view.mdx) or [read document information](./document-information.mdx).
:::

## 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](../api-references/web-sdk/namespaces/Pdf/classes/Controller.md) ➡️ [ControllerEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/ControllerEventMap.md)
- [Document](../api-references/web-sdk/namespaces/Pdf/classes/Document.md) ➡️ [DocumentEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/DocumentEventMap.md)
- [DocumentView](../api-references/web-sdk/namespaces/UI/classes/DocumentView.md) ➡️ [DocumentViewEventMap](../api-references/web-sdk/namespaces/UI/interfaces/DocumentViewEventMap.md)
- [Page](../api-references/web-sdk/namespaces/Pdf/classes/Page.md) ➡️ [PageEventMap](../api-references/web-sdk/namespaces/Pdf/interfaces/PageEventMap.md)

## 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-web-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 = number * 100;
    console.log(`zoom changed to ${percent}%`);
  };

  documentView.addEventListener('zoomChanged', zoomListener);
  documentView.initialize(pdfDocument);
}

initialize();
```

---

## Release notes

Learn about the changes, additions, and fixes in the PDF Viewer SDK.

## Version 5

### 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 the [Enable accessibility layer](./standard-implementation/customize-viewer.mdx#enable-accessibility-layer) section.
- You can add custom headers using HTTP requests when opening a document, improving integration flexibility. For more information, review the [Provide custom HTTP headers when opening a document](./standard-implementation/customize-viewer.mdx#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](./api-references/web-sdk/namespaces/Pdf/classes/Page.md) 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](./api-references/web-sdk/namespaces/Pdf/namespaces/Annotations/classes/TextMarkupAnnotation.md) in the PDF Wev 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 the [Modify save button behavior](./standard-implementation/customize-viewer.mdx#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 the [Disable auto-repair feature](./standard-implementation/customize-viewer.mdx#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](../../pdf-web-viewer_versioned_docs/version-4/release-notes.mdx).
:::

---

## Standard implementation overview

import DocCardList from '@theme/DocCardList';

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

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 `overrideButtonBehaviour` 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 pdfWebViewer = await PdfToolsViewer.initialize();
  const container = document.getElementById("pdftools-web-viewer-container");
  container.append(pdfWebViewer);

  // Overrides the "Save" button to download the original document without changes made in the viewer.
  pdfWebViewer
    .api()
    .toolbar.button.overrideBehaviour(
      pdfWebViewer,
      "pdftools-icon-button-save",
      () => {
        pdfWebViewer.api().document.save(pdfWebViewer, { saveOriginal: true });
      }
    );
}

initialize();
```

## Disable auto-repair feature

Disable automatic repair operations on PDF files by setting the `autoRepairDisabled` property to `true` in the `open` method 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 pdfWebViewer = await PdfToolsViewer.initialize();
  const container = document.getElementById("pdftools-web-viewer-container");
  container.append(pdfWebViewer);

  // URL of the PDF file (as a string)
  const url: string = "https://example.com/sample.pdf";

  pdfWebViewer.api().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 pdfWebViewer = await PdfToolsViewer.initialize({
    accessibilityLayerEnabled: true,
  });
  const container = document.getElementById("pdftools-web-viewer-container");
  container.append(pdfWebViewer);
}

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 pdfWebViewer = await PdfToolsViewer.initialize();
  const container = document.getElementById("pdftools-web-viewer-container");
  container.append(pdfWebViewer);

  // URL of the PDF file (as a string)
  const url: string = "https://example.com/sample.pdf";

  pdfWebViewer.api().document.open({
    uri: url,
    httpOptions: {
      headers: {
        Authorization: "Bearer [TOKEN]",
      },
    },
  });
}

initialize();
```

---

## View a PDF

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 pdfWebViewer = await PdfToolsViewer.init();
  const container = document.getElementById("pdftools-web-viewer-container");
  container.append(pdfWebViewer);
}

initialize();
```

---

## Other shell tools and SDKs

The category of other shell tools and SDKs includes documentation of products whose functionality was or will be replaced by other SDKs. Before using these products, please check whether our current products cover their functionality. The current products include:

- [Pdftools SDK](../pdf-tools-sdk/)
- [Conversion Service](../conversion-service/)
- [PDF Viewer SDK](../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/).

---

## Code samples for Image to PDF Converter

:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/convert/)**.
:::

Image to PDF Converter lets you convert image files to PDF documents, including PDF/A with searchable output files. Here you'll find some examples of how to integrate the code in your development.

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## Image to PDF Converter documentation

The Image to PDF Converter has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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](image-pdf-converter-code.mdx)** 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
Download a full sample of image to PDF conversion using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Img2PdfDefault/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/MultipleImg2Pdf/Download?technology=Python).
:::

---

## Documentation for other products

Here you can find all the documentation you need for previous Pdftools products.

## Document Converter
The 3-Heights® Document Converter is a service-based application for converting a wide range of document formats to PDF or TIFF.    
The features offered by this product are now available with [Conversion Service](https://www.pdf-tools.com/products/conversion/conversion-service/).

- **[Enterprise edition](https://pdf-tools.com/public/downloads/manuals/DocumentConverterEnterprise.pdf)**    
- **[SME edition](https://pdf-tools.com/public/downloads/manuals/DocumentConverterSME.pdf)**    
- **[Client](https://pdf-tools.com/public/downloads/manuals/DocumentConverterClient.pdf)**   
- **[API](https://www.pdf-tools.com/public/downloads/manuals/DocumentConverterApi.pdf)**   

## 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)**   

## PDF Producer
3-Heights® PDF Producer lets you Create files conforming to PDF and PDF/A from any Windows application via the print function.

- **[User guide](https://pdf-tools.com/public/downloads/manuals/PdfProducer.pdf)**

## Batch Stamp Tool
The PDF Batch Stamp Tool lets you create textual or image stamps on PDF documents.    
[Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/) now provides features of the PDF Batch Stamp Tool. Previously, [PDF Security](./pdf-security.mdx) also offered similar functionality, but it has been replaced with the [Pdftools SDK](https://www.pdf-tools.com/products/conversion/pdf-tools-sdk/) also.

- **[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)**

## PDF OCR
3-Heights® PDF OCR lets you enhance PDF documents using information detected by an OCR engine.

- **[Enterprise Add-on](https://pdf-tools.com/public/downloads/manuals/PdfOcrEnterprise.pdf)**   
- **[API](https://pdf-tools.com/public/downloads/manuals/pdfocrapi.pdf)**   
- **[Shell](https://pdf-tools.com/public/downloads/manuals/PdfOcrShell.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)**

## Scan to PDF Server
The 3-Heights® Scan to PDF Server is a service-based application for scan post processing. 

- **[User guide](https://pdf-tools.com/public/downloads/manuals/Scan2PdfServer.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.
          
          
            
              
                Developer guide
              
            
          
        
      
    
    
      
        
          
             API
          
          
            Send API calls to validate and fix PDFs.
          
          
            
              
                Developer guide
              
            
          
        
      
    
  

:::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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

:::info Extract with Pdftools SDK
This product has been replaced by the **[Pdftools SDK](../../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.
            
          
          
            
              
                Developer guide
              
            
          
        
      
    
    
      
        
          
             API
          
          
            
              Send API calls to transform PDF content and metadata into useable
              information.
            
          
          
            
              
                Developer guide

---

## Code samples for PDF to Image Converter

:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/convert/)**.
:::

PDF to Image Converter lets you transform PDF documents into single page or multi-page raster images such as TIFF or JPEG. Here you'll find some examples of how to integrate the code in your development.

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## PDF to Image Converter documentation

The PDF to Image Converter has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/convert/)**, providing improved performance, quality and reliability. On this page, you can learn how to migrate from the PDF to Image Converter to the Pdftools SDK.

:::caution PDF to Image Converter documentation and code samples

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/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.

You can also explore the **[code samples](pdf-image-converter-code.mdx)** for examples of how to use the PDF to Image Converter API.
:::

## Migrate from the PDF to Image Converter to the Pdftools SDK

Migrate to the Pdftools SDK to use a streamlined interface for converting PDF documents to rasterized images.

:::tip Pdftools SDK quick start
Download a full sample of PDF to image conversion using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Pdf2ImgSimple/Download?technology=Python).
:::

---

## PDF Merge Split documentation

PDF Merge / Split has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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
Download a full sample of assembling PDF documents using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/Merge/Download?technology=Python).
:::

---

## Code samples for PDF Optimizer

:::caution Product update
The PDF Optimizer has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/optimize/)**.

See the [Migrate from the PDF Optimizer to the Pdftools SDK](./pdf-optimizer.mdx) documentation.
:::

PDF Optimizer lets you compress and optimize PDFs for the web, printing, and long-term archiving. Here are some examples of how to integrate the code in your development.

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## PDF Optimizer documentation

The PDF Optimizer has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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](pdf-optimizer-code.mdx)** 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
Download a full sample of PDF optimization using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/OptimizerSimple/Download?technology=Python).
:::

### 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](../../pdf-tools-sdk/toolbox/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](../../pdf-tools-sdk/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](../../pdf-tools-sdk/toolbox/extract/) from a PDF file before optimizing.

### Set document metadata and information

Refer to the Toolbox add-on documentation to [manage metadata](../../pdf-tools-sdk/toolbox/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 &lt;title&gt;
    
    
      -a &lt;author&gt;
    
    
      -s &lt;subject&gt;
    
    
      -k &lt;keyword1,keyword2&gt; etc.
    
    
      -c &lt;creator&gt;
    
    
      -cd &lt;creation date&gt;
    
    
      -md &lt;modification date&gt;
    
    
      -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 &lt;perms&gt;
    
    
      -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 &lt;perms&gt; 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

import { CodeSamples } from '@site/src/components/CodeSamples'

:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/archive/)**.
:::

PDF to PDF/A Converter converts PDFs to PDF/A format. Here you'll find some examples of how to integrate the code in your development.

---

## PDF to PDF/A Converter documentation

The PDF to PDF/A Converter has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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](pdf-pdfa-converter-code.mdx)** 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
Download a full sample of PDF to PDF/A conversion using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateConvert/Download?technology=Python).
:::

---

## Code samples for PDF Printer

import { CodeSamples } from '@site/src/components/CodeSamples'

With PDF Printer, you can send multiple documents in a single job, send multiple jobs, and even customize the print settings used. 
Here you'll find some examples of how to integrate the code in your development.

---

## 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.
          
          
            
              
                Developer guide
              
            
          
        
      
    
    
      
        
          
             API
          
          
            
              Send API calls to transform PDF content and metadata into useable
              information.
            
          
          
            
              
                Developer guide
              
            
          
        
      
    
  

:::tip See it in action!
Check out the **[code samples](pdf-printer-code.mdx)** 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).
:::

---

## Code samples for PDF Security

import { CodeSamples } from '@site/src/components/CodeSamples'

:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/sign-and-secure/)**.  
:::

With PDF Security, you can digitally sign multiple PDF documents using online signing services and local certificates. Here you'll find some of some examples of how to integrate the code in your development.

---

## PDF Security documentation

PDF Security has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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](pdf-security-code.mdx)** 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
Download a full sample of signing a PDF using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/BuiltInSign/Download?technology=Python).
:::

---

## Code samples for PDF Validator

:::caution Product update
This product has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/validate/)**.
:::

PDF Validator lets you check single documents or an entire batch for conformance with the ISO PDF and PDF/A standards. Here you'll find some examples of how to integrate the code in your development.

import { CodeSamples } from '@site/src/components/CodeSamples'

---

## PDF Validator documentation

The PDF Validator has been replaced by the **[Pdftools SDK](../../pdf-tools-sdk/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 samples

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](pdf-validator-code.mdx)** 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
Download a full sample of PDF/A validation using the Pdftools SDK in [C#](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=CS), [Java](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=Java), [C](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=C), and [Python](https://www.pdf-tools.com/api/v1.0/Samples/_PDFSDK/ValidateSimple/Download?technology=Python).
:::

---

## Pdftools Technical Support

We're happy to help with any questions about our products. We've been leading the way in PDF technology 20+ years.  
So you count on the developer experience and support you need, when you need it.

:::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 [My PDF Tools Portal](https://portal.pdf-tools.com/intermediate).
- If this does not solve your issue, contact Pdftools Technical Support.

:::

## What do I need to include in my support case?

When you open a support case, indicate:

- The product affected.
- The version installed.
- Any support logs (if available).

Log in to your My PDF Tools Portal account:
  
    Open support case
  
  
  Don't have access? Contact us

---

:::note Feedback on our docs?

Missing information from the docs? Didn't quite cover your specific use case?

Send ideas and suggestions to documentation@pdf-tools.com .

:::

---

## 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     |

---

## April 2025

In April 2025, the Pdftools documentation included the following updates:

## Added

- The Pdftools SDK [version 1.9.1](/docs/pdf-tools-sdk/release-notes/#version-191) patch release notes and the Toolbox add-on [version 1.6.1](/docs/pdf-tools-sdk/release-notes/#version-161) patch release notes.
- The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.7](/docs/pdf-tools-sdk/release-notes/#version-17-2) release notes.
- Conversion Service release notes [version 6.1.0](/docs/conversion-service/release-notes/#610). This update also included significant additions and updates for the:
    - [Simple API Postman collection](pathname:///files/conversion-service/conversion_service_simple_api.postman_collection.json)
    - [Simple API reference](/docs/conversion-service/api/simple-api/simple-api/)
- Added the Conversion Service [version 5.7.5](/docs/conversion-service/release-notes/#575) LTS patch release notes.
- The Conversion Service [Dossier workflow](/docs/conversion-service/workflows/dossier/) page received a major update, including new infographics and many textual improvements.
- Major update of the [Automatic update](/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](/docs/pdf-web-viewer/release-notes/#version-550) release notes and [API references](/docs/pdf-web-viewer/category/api-references/). Also, the following code snippets and their descriptions were added:
    - [Enable accessibility layer](/docs/pdf-web-viewer/standard-implementation/customize-viewer/#enable-accessibility-layer)
    - [Provide custom HTTP headers when opening a document](/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](/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](/docs/conversion-service/integrate/connectors/) page.
- Algolia search improvements.

---

## February 2025

In February 2025, the Pdftools documentation included the following updates:

## Added

- All release notes, such as the [Pdftools SDK](../../pdf-tools-sdk/release-notes/#pdftools-sdk), [Toolbox add-on](../../pdf-tools-sdk/release-notes/#toolbox-add-on), [Conversion Service](../../conversion-service/release-notes/), and the PDF Viewer SDK (both [version 5](../../pdf-web-viewer/release-notes/) and [version 4](../../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](/docs/conversion-service/configure/office-conversion/) guide.
- The [Update Conversion Service on Windows Server](../../conversion-service/update/windows-server/) and [Update Conversion Service in Docker](../../conversion-service/update/docker/) guides received major updates in their structure and delivery.
- [Conversion Service on Windows Server](/docs/conversion-service/getting-started/windows-server/) getting started guide and [Conversion Service in Docker getting started](/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](../../pdf-web-viewer/release-notes/#version-520) and [5.3.0](../../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](../../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](/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.

---

## 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](../../pdf-tools-sdk/release-notes/#version-18).
- The Toolbox add-on received an update to version 1.5.0. Review the [release notes](../../pdf-tools-sdk/release-notes/#version-15-1) for more details.
- LTS version of the PDF Viewer SDK received a 4.3.4 patch. Review the [4.3.4 release notes](../../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](../../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](../../licenses/#frequently-asked-questions).
- The Pdftools SDK Shell Tool documentation now includes the [Pdftools SDK Shell Tool 1.6](/docs/pdf-tools-sdk/release-notes/#version-16-2) release notes.

## Changed

- Link to our Discord channel was removed. If you need our support, please reach out through the [support page](../../support/).

## Fixed

- Pdftools SDK [Python getting started](../../pdf-tools-sdk/getting-started/pdftools-sdk/pdftools-sdk-python/) received a major update and fixes.
- The [Toolbox add-on getting started guides](../../pdf-tools-sdk/getting-started/toolbox/) also received minor fixes and updates.
- [PDF Viewer SDK standard implementation](../../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](../../pdf-web-viewer/standard-implementation/view-pdf/)
    - [Customize the PDF Viewer SDK](../../pdf-web-viewer/standard-implementation/customize-viewer/)

---

## 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](/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](/docs/pdf-tools-sdk/release-notes/#version-18-2).
- The Toolbox add-on received release notes for [version 1.8.0](/docs/pdf-tools-sdk/release-notes/#version-18-1) with updated API reference links and code samples.
- Pdftools SDK licensing docs now include the [Configure proxy](/docs/licenses/products/pdf-tools-sdk-license/#configure-proxy) and [Operations](/docs/licenses/products/pdf-tools-sdk-license/#operations) sections.
- Conversion Service release notes for [version 6.3.0](/docs/conversion-service/release-notes/#630) have been added. The following documents received an update:
    - [Configure stamps and annotations](/docs/conversion-service/configure/configure-stamping/) documentation.
    - [Stamp and annotation](/docs/conversion-service/workflows/stamping/) workflow documentation.
    - Minor updates in the [Cryptographic providers](/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)](/docs/conversion-service/configure/office-conversion/#the-server-process-could-not-be-started-because-the-configured-identity-is-incorrect-com-exception-0x8000401a).
        - [Access is denied (COM exception 0x80070005)](/docs/conversion-service/configure/office-conversion/#access-is-denied-com-exception-0x80070005)
- Conversion Service OCR documentation now includes online ABBYY  license type information in the [Activate ABBYY license](/docs/conversion-service/configure/configure-ocr/#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](/docs/licenses/configure/docker-licensing-gateway-service/) and links you to the Conversion Service [Configure containers using Docker Compose](/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](/docs/conversion-service/getting-started/windows-server/) and [Docker](/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](/docs/pdf-web-viewer/release-notes/#version-560) and updated [API references](/docs/pdf-web-viewer/category/api-references/).
- Legacy Toolbox SDK received patches [version 4.4.10](/docs/pdf-toolbox-sdk/release-notes/#version-4410) and [version 4.4.11](/docs/pdf-toolbox-sdk/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](/docs/pdf-tools-sdk/tags/)
    - [Conversion Service tags](/docs/conversion-service/tags/)
    - [PDF Viewer SDK tags](/docs/pdf-web-viewer/tags/)
    - Example: Try clicking on a tag like [Merge and split PDFs](/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](/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](/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 new [Pdftools Portal](https://portal.pdf-tools.com/) have been updated. Despite the new [Pdftools Portal](https://portal.pdf-tools.com/), some products and license keys are only accessible in the legacy portal. Select which customer portal to access on the [Select your login](https://portal.pdf-tools.com/intermediate) page.
- All pages in the Conversion Service [Workflows](/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](/docs/pdf-tools-sdk/e-invoice/) and a related code sample, [Create a ZUGFeRD invoice](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/#create-a-zugferd-invoice). You can use the provided information and code sample to create e-invoices in both ZUGFeRD and Factur-X formats.
- Pdftools SDK [version 1.9](/docs/pdf-tools-sdk/release-notes/#version-19) release notes and Toolbox add-on [version 1.6](/docs/pdf-tools-sdk/release-notes/#version-16-1) release notes.
- Conversion Service release notes for [version 6.0.0](/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](/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](/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](/docs/conversion-service/getting-started/windows-server/) getting started guide.
- PDF Viewer SDK [version 5.4.0](/docs/pdf-web-viewer/release-notes/#version-540) release notes. The PDF Viewer SDK [API references](/docs/pdf-web-viewer/category/api-references/) were also updated.
- Added [PDF Toolbox SDK 4.4.9](/docs/pdf-toolbox-sdk/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](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/) or [Toolbox add-on code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/), must be downloaded so you can use them.
- The optional [Install and configure additional clients](/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](/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](/docs/support/release-management/#supported-lts-product-releases) table in [Release management](/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](/docs/conversion-service/) documentation.
- Removed repeated word **Configure** in nearly every Conversion Service [Configure](/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](/docs/licenses/configure/offline-licensing-gateway-service/) for more information.

---

## 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](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-samples/)
    - [Toolbox add-on code samples](/docs/pdf-tools-sdk/code-samples/pdftools-sdk-toolbox-samples/)
- Release notes for the Pdftools SDK versions [1.10](/docs/pdf-tools-sdk/release-notes/#version-110), [1.11](/docs/pdf-tools-sdk/release-notes/#version-111), and patch [1.11.1](/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](/docs/pdf-tools-sdk/release-notes/#version-17-1) and patch [version 1.7.1](/docs/pdf-tools-sdk/release-notes/#version-171).
- The Conversion Service documentation now includes release notes for [version 6.2.0](/docs/conversion-service/release-notes/#620). This version came with the following documentation updates:
    - The [Licensing Gateway Service (LGS) full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) is now enabled for the Conversion Service.
    - The [Accessibility workflow](/docs/conversion-service/workflows/accessibility/) initial documentation has been published.
- The [Licensing credit count](/docs/licenses/products/pdf-tools-sdk-license/#licensing-credit-count) and [Calculating credits](/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](/docs/conversion-service/release-notes/#620) release notes.
- The legacy [Customer portal](https://my.pdf-tools.com/en/mypdftools/licenses-kits/) URL was changed from `https://www.pdf-tools.com/en/mypdftools/licenses-kits/` to `https://my.pdf-tools.com/en/mypdftools/licenses-kits/`. Note that there is now a new customer portal. However, some products and license keys are only accessible in the legacy portal. You can select which customer portal to access on the [Select your login](https://portal.pdf-tools.com/intermediate) page.

## Fixed

- The [Convert Microsoft Office files](/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](/docs/conversion-service/) documentation landing page, [Conversion Service in Docker](/docs/conversion-service/getting-started/docker/) guide, PDF Viewer SDK [Custom implementation guides](/docs/pdf-web-viewer/guides/), and the [Full offline mode](/docs/licenses/configure/offline-licensing-gateway-service/) licensing documentation.
- General deployment processes for documentation have been enhanced to ensure greater stability and accessibility.