QuantaPDF

KO | EN

gitlite — search

#developer-tools #anthropic #artificial-intelligence #sql #ui #cli #monitoring #swift #electron #web

(★ 8)

Extract image and text from PDF file by mupdf

File Explorer

ZIP Download

- - ci.yml
- quantapdf-v2.exports
- CheckQuantaPDFExports.cmake
- QuantaPDFExports.cmake
- QuantaPDFPdfium.cmake
- - v2.3.0.md
  - v2.5.0.md
  - v2.6.0.md
- - quantapdf.h
- BuildPresets.json
- Compilers.json
- ConfigurePresets.json
- Options.json
- Platforms.json
- TestPresets.json
- - base14_metrics.h
  - jpeg_encoder.cpp
  - jpeg_encoder.h
  - jpeg_validator.c
  - pdfium_document.cpp
  - pdfium_document.h
  - pdfium_runtime.cpp
  - pdfium_runtime.h
  - qpdf_composer.cpp
  - qpdf_composer.h
  - qpdf_document.cpp
  - qpdf_document.h
  - qpdf_edit.h
  - secure_random.cpp
  - secure_random.h
- annotation_snapshot.h
- composer.c
- document.c
- form_snapshot.h
- image_bitmap.c
- image_snapshot.h
- images.c
- input_file.c
- input_file.h
- internal.h
- link_snapshot.h
- links.c
- outline_snapshot.h
- output_file.c
- page.c
- pdf_annotations.c
- pdf_crop.c
- pdf_edit.c
- pdf_edit_annotations.c
- pdf_edit_forms.c
- pdf_edit_internal.h
- pdf_export.c
- pdf_flatten.c
- pdf_form.c
- pdf_image_recompression.c
- pdf_merge.c
- pdf_metadata.c
- pdf_outline.c
- pdf_poster.c
- pdf_range.c
- pdf_rewrite.c
- pdf_security.c
- pdf_security_rewrite.c
- pdf_trim.c
- render.c
- search.c
- status.c
- structured_text.c
- text.c
- text_snapshot.h
- - acroform-annots-nonarray.pdf
  - acroform-bad-button-ap.pdf
  - acroform-bad-ff.pdf
  - acroform-bad-fields.pdf
  - acroform-bad-ft.pdf
  - acroform-bad-i.pdf
  - acroform-bad-kid.pdf
  - acroform-bad-opt.pdf
  - acroform-bad-root.pdf
  - acroform-bad-signature.pdf
  - acroform-bad-value.pdf
  - acroform-bad-widget-flags.pdf
  - acroform-bad-widget-rect.pdf
  - acroform-choice.pdf
  - acroform-cycle.pdf
  - acroform-depth-257.pdf
  - acroform-direct-widget.pdf
  - acroform-duplicate-name.pdf
  - acroform-duplicate-widget.pdf
  - acroform-empty-fields.pdf
  - acroform-group-conflict.pdf
  - acroform-js.pdf
  - acroform-late-malformed.pdf
  - acroform-main.pdf
  - acroform-missing-widget.pdf
  - acroform-mixed-group.pdf
  - acroform-mutation-bad-need-appearances.pdf
  - acroform-mutation-basic.pdf
  - acroform-mutation-choice.pdf
  - acroform-mutation-direct-field-pdfium.pdf
  - acroform-mutation-direct-field.pdf
  - acroform-mutation-events.pdf
  - acroform-mutation-groups-pdfium.pdf
  - acroform-mutation-groups.pdf
  - acroform-mutation-modes-pdfium.pdf
  - acroform-mutation-modes.pdf
  - acroform-mutation-need-appearances.pdf
  - acroform-mutation-xfa.pdf
  - acroform-no-fields.pdf
  - acroform-orphan-widget.pdf
  - acroform-p-mismatch.pdf
  - acroform-parent-mismatch.pdf
  - acroform-period-name.pdf
  - acroform-repeated-node.pdf
  - acroform-root-parent.pdf
  - acroform-scalars.pdf
  - acroform-stream-value.pdf
  - acroform-structure.pdf
  - acroform-widgets.pdf
  - annotation-mutation-js.pdf
  - annotation-mutation-signed.pdf
  - annotation-mutation-unsigned-signature.pdf
  - annotation-mutation.pdf
  - annotations-filtered-only.pdf
  - annotations-late-malformed.pdf
  - annotations-mixed.pdf
  - annotations-nonarray.pdf
  - composition-non-pdf.txt
  - composition-three-page.pdf
  - crop-cropbox-outside-media.pdf
  - crop-inherited.pdf
  - crop-interactive.pdf
  - crop-malformed-box.pdf
  - crop-malformed-rotate.pdf
  - crop-malformed-userunit.pdf
  - crop-rotate-90.pdf
  - crop-userunit.pdf
  - encrypted-one-page.pdf
  - flatten-appearance-malformed.pdf
  - flatten-appearance.pdf
  - flatten-basic.pdf
  - flatten-combined-order.pdf
  - flatten-contents-malformed.pdf
  - flatten-contents.pdf
  - flatten-flag-isolation.pdf
  - flatten-form-ancestor-survives.pdf
  - flatten-form-closure.pdf
  - flatten-form-co-cow.pdf
  - flatten-form-cow.pdf
  - flatten-form-deep-survivor.pdf
  - flatten-form-deep.pdf
  - flatten-form-kids-cow.pdf
  - flatten-form-multi-root.pdf
  - flatten-multi-widget.pdf
  - flatten-noop-malformed-acroform.pdf
  - flatten-noop-malformed-annots.pdf
  - flatten-noop-neutral-link.pdf
  - flatten-noop-zero-widget.pdf
  - flatten-number-format.pdf
  - flatten-policy-annotation-with-widget.pdf
  - flatten-policy-irt-forward.pdf
  - flatten-policy-irt-reverse.pdf
  - flatten-policy-link-apn.pdf
  - flatten-policy-link-bad-border.pdf
  - flatten-policy-link-bad-w.pdf
  - flatten-policy-link-border0.pdf
  - flatten-policy-link-bs-malformed.pdf
  - flatten-policy-link-bs-missing-w.pdf
  - flatten-policy-link-bs0-border4.pdf
  - flatten-policy-link-bs0.pdf
  - flatten-policy-link-bs4-border0.pdf
  - flatten-policy-link-default.pdf
  - flatten-policy-needappearances-false.pdf
  - flatten-policy-needappearances-malformed.pdf
  - flatten-policy-needappearances-true.pdf
  - flatten-policy-popup-direct.pdf
  - flatten-policy-popup-parent-reverse.pdf
  - flatten-policy-subtype-file-attachment.pdf
  - flatten-policy-subtype-redact.pdf
  - flatten-policy-subtype-rich-media.pdf
  - flatten-policy-subtype-unknown.pdf
  - flatten-policy-xfa.pdf
  - flatten-tagged-noop.pdf
  - flatten-tagged.pdf
  - flatten-widget-as.pdf
  - flatten-widget-radio-as.pdf
  - flatten-widgets.pdf
  - image-recompression-expected-q90.pdf.base64
  - metadata-info.pdf
  - one-page.pdf
  - outline-cycle.pdf
  - outline-depth-257.pdf
  - outline-repairable-bad.pdf
  - outline-tree.pdf
  - page-boxes.pdf
  - page-images-alpha.pdf
  - page-images.pdf
  - page-links.pdf
  - poster-basic.pdf
  - poster-crossing-annotation.pdf
  - poster-crossing-widget.pdf
  - poster-field-action.pdf
  - poster-form-actions.pdf
  - poster-interactive.pdf
  - poster-malformed-annots.pdf
  - poster-malformed-destination.pdf
  - poster-navigation-rotate-90.pdf
  - poster-navigation-userunit.pdf
  - poster-navigation.pdf
  - poster-nonxyz-destination.pdf
  - poster-nullxyz-destination.pdf
  - poster-orphan-widget.pdf
  - poster-outline-unsupported-action.pdf
  - poster-outside-destination.pdf
  - poster-production-box.pdf
  - poster-root-policy.pdf
  - poster-rotate-90.pdf
  - poster-tagged.pdf
  - poster-unselected-actions.pdf
  - poster-unselected-annot-action.pdf
  - poster-userunit.pdf
  - structured-text.pdf
  - text-one-page.pdf
  - trim-default-boxes.pdf
  - trim-interactive.pdf
  - trim-malformed-box.pdf
  - trim-malformed-rotate.pdf
  - trim-malformed-userunit.pdf
  - trim-preserved-crop.pdf
  - trim-rotate-90.pdf
  - trim-userunit.pdf
  - truncated.pdf
  - two-page.pdf
- CMakeLists.txt
- composer_test_helpers.cpp
- composer_test_helpers.h
- fake_dumpbin.c
- flatten_test_helpers.cpp
- image_recompression_test_helpers.cpp
- image_recompression_test_helpers.h
- pdf_edit_fault_hook.c
- pdf_edit_test_api.h
- pdf_image_recompression_fault_hook.c
- pdf_image_recompression_test_api.h
- pdf_poster_fault_hook.c
- pdf_poster_test_api.h
- pdf_security_rewrite_fault_hook.c
- pdf_security_rewrite_test_api.h
- pdf_security_rewrite_test_helpers.cpp
- pdf_security_test_helpers.cpp
- qpdf_test_helpers.cpp
- rewrite_test_helpers.cpp
- test_backend_foundation.c
- test_composer.c
- test_document.c
- test_image_bitmap.c
- test_images.c
- test_jpeg_encoder.cpp
- test_jpeg_validator.c
- test_links.c
- test_output_file.c
- test_pdf_annotation_mutation.c
- test_pdf_annotations.c
- test_pdf_crop.c
- test_pdf_crop_internal.h
- test_pdf_crop_transforms.c
- test_pdf_delete.c
- test_pdf_export.c
- test_pdf_flatten.c
- test_pdf_form.c
- test_pdf_form_appearance.c
- test_pdf_form_mutation.c
- test_pdf_form_mutation_main.c
- test_pdf_form_rollback.c
- test_pdf_image_recompression.c
- test_pdf_image_recompression_semantics.c
- test_pdf_merge.c
- test_pdf_metadata.c
- test_pdf_order.c
- test_pdf_outline.c
- test_pdf_poster_split.c
- test_pdf_poster_split_batch.c
- test_pdf_poster_split_geometry.c
- test_pdf_poster_split_interactive.c
- test_pdf_poster_split_internal.h
- test_pdf_poster_split_main.c
- test_pdf_poster_split_navigation.c
- test_pdf_poster_split_policy.c
- test_pdf_range.c
- test_pdf_rewrite_lossless.c
- test_pdf_security.c
- test_pdf_security_rewrite.c
- test_pdf_security_rewrite_semantics.c
- test_pdf_trim.c
- test_pdf_trim_batch.c
- test_pdf_trim_internal.h
- test_pdf_trim_main.c
- test_pdf_trim_outside_crop.c
- test_pdf_trim_policy.c
- test_pdf_trim_required.c
- test_pdf_trim_transforms.c
- test_render.c
- test_status.c
- test_structured_text.c
- test_text.c
- test_text_search.c
- test_version.c
.gitattributes
.gitignore
CMakeLists.txt
CMakePresets.json
CMakeUserPresets.json
LICENSE
README.md
THIRD_PARTY.md
vcpkg.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**QuantaPDF — PDF made easy.**

QuantaPDF is a compact native PDF kernel with a versioned C11 ABI suitable for
native callers and .NET P/Invoke.

> **Backends:** QuantaPDF uses pinned PDFium `154.0.8021.0` for document
> inspection, rendering, and extraction, plus qpdf `12.4.0` for structural
> transforms and editing. Both remain private implementation dependencies.

## Current v2 ABI

The v2 ABI uses the `quantapdf_*` symbol/type prefix and `QUANTAPDF_*`
constants throughout. `<quantapdf/quantapdf.h>` is the sole public header;
the previous namespace and compatibility wrappers are not retained.

Document lifecycle remains the root of the API:

```c
#include <quantapdf/quantapdf.h>

quantapdf_document *doc = NULL;
int pages = 0;

if (quantapdf_open("file.pdf", NULL, &doc) == QUANTAPDF_OK) {
    if (quantapdf_page_count(doc, &pages) == QUANTAPDF_OK) {
        /* use pages */
    }
    quantapdf_close(doc);
}
```

Page + Render adds opaque page and bitmap handles:

```c
quantapdf_page *page = NULL;
quantapdf_bitmap *bitmap = NULL;
int width, height, stride, components;

if (quantapdf_load_page(doc, 0, &page) == QUANTAPDF_OK) {
    if (quantapdf_render_page(page, &bitmap) == QUANTAPDF_OK) {
        quantapdf_bitmap_dimensions(
            bitmap, &width, &height, &stride, &components);
        /* inspect bitmap data */
        quantapdf_drop_bitmap(bitmap);
    }
    quantapdf_drop_page(page);
}
```

The current supported surface includes:

- document open / password authentication / page count / close
- opaque page load / drop
- page bounds plus MediaBox/CropBox bounds
- RGB and RGBA page rendering
- DPI/zoom, rotation, and page-space clipping
- aspect-preserving thumbnail rendering
- bitmap dimensions and borrowed sample access
- plain UTF-8 text extraction
- immutable structured-text snapshots and geometric text search
- page-image enumeration and image bitmap rendering
- URI/internal links, annotations, document metadata, and outlines
- immutable AcroForm snapshots and isolated PDF edit sessions
- page export/range export, output merging, and file saving
- catalog-reachable document security audit and immutable policy sanitization
- explicit AES-256 encrypt, authenticated decrypt, and re-encrypt transforms
- immutable CropBox crop, MediaBox trim, poster-split, interactive-content
  flattening, lossless rewrite/GC, and selective image recompression transforms
- deterministic PDF composition from formatted base-14 text and JPEG/PNG images
- stable status strings and one allocator-matched `quantapdf_free()` entry point

## API contract

- The public header contains no PDFium or qpdf types.
- Backend handles and C++ exceptions remain private to the library.
- `quantapdf_page` and `quantapdf_bitmap` borrow their parent document. The document must outlive all derived page and bitmap handles.
- A bitmap does not borrow its source page after rendering, so the page may be dropped before the bitmap, provided the document remains alive.
- PDFium process state is private, initialized once, and serialized by the
  backend runtime because PDFium's public API is not thread-safe.
- Input paths are UTF-8.
- `password == NULL` means no password was supplied.
- Missing or incorrect passwords return `QUANTAPDF_ERROR_PASSWORD`.
- `quantapdf_open` accepts PDF input; non-PDF data returns
  `QUANTAPDF_ERROR_FORMAT`.
- `quantapdf_open` leaves the output handle NULL on failure.
- `quantapdf_close(NULL)`, `quantapdf_drop_page(NULL)`, and `quantapdf_drop_bitmap(NULL)` are safe.
- qpdf and standard C++ exceptions are caught inside the private bridge and
  translated to `quantapdf_status`.
- ABI v2 requires external serialization: applications must not execute
  `quantapdf_*` calls concurrently, including calls that use different
  documents or otherwise unrelated handles.

Snapshot/output ownership is explicit:

- `quantapdf_text_page`, `quantapdf_link_page`, `quantapdf_outline`,
  `quantapdf_annotation_page`, `quantapdf_form`, and `quantapdf_output`
  own their copied observations and remain valid for their documented snapshot lifetime;
- pointers returned by snapshot string/data accessors are borrowed until the
  corresponding snapshot/output is dropped;
- strings returned through `char **` outputs are caller-owned and must be
  released with `quantapdf_free()`;
- `quantapdf_pdf_edit` owns a private PDF graph and never mutates its source
  `quantapdf_document`.
- `quantapdf_composer` copies text and image inputs at each successful add/draw
  call. Every successful `quantapdf_composer_finish()` returns an independent
  `quantapdf_output`; finish does not consume or freeze the composer.

## ABI-sized structures

The installed header publishes `QUANTAPDF_VERSION_MAJOR`,
`QUANTAPDF_VERSION_MINOR`, `QUANTAPDF_VERSION_PATCH`, and
`QUANTAPDF_ABI_VERSION`. ABI version 2 follows these compatibility rules:

- existing exported functions, enum numeric values, structure fields, and
  ownership rules are not removed, reordered, or reinterpreted;
- new functions and enum values may be appended;
- incompatible changes require a new ABI version and shared-library major
  version.

`struct_size` has two distinct contracts:

- Single option/info structures are append-only. A library reads or writes
  only fields covered by the caller-provided size.
- Structures traversed as C array elements have fixed V1 layouts because an
  array has no independent element-stride metadata. These currently include
  `quantapdf_page_crop`, `quantapdf_page_trim`,
  `quantapdf_page_poster_split`, `quantapdf_search_result`, and
  `quantapdf_form_value_input`. Their accepted `struct_size` range is the
  matching `QUANTAPDF_*_V1_MIN_SIZE` through `QUANTAPDF_*_V1_SIZE`; values
  larger than the fixed V1 layout are rejected. Future extensions require a
  new type/API or an API carrying an explicit element stride.

## Page coordinates

All public page rectangles use **displayed page space** rather than raw PDF object coordinates:

- the CropBox top-left is the page-space origin `(0, 0)`;
- x increases to the right;
- y increases downward;
- values are page points before render scaling (`72 points = 1 inch`).

`quantapdf_page_box_bounds(..., QUANTAPDF_PAGE_BOX_MEDIA, ...)` may therefore have negative coordinates when MediaBox extends outside CropBox.

This same page-space contract is intended for later text geometry, search quads, images, links, and annotations.

Intrinsic format-specific rotation metadata is intentionally not part of the generic Page API. Page bounds already describe displayed geometry, including `/Rotate` and `/UserUnit`; raw rotation metadata, if needed by callers, belongs in a later PDF-specific metadata surface. Rendering rotation is explicit and per-call.

## PDF composition

The Composer facade creates new PDFs without exposing qpdf or PDFium types.
Coordinates use the same top-left, y-down point space as the Page API:

```c
quantapdf_composer *composer = NULL;
quantapdf_output *output = NULL;
size_t page_index = 0;

quantapdf_composer_page_options page = {
    .struct_size = sizeof(quantapdf_composer_page_options),
    .width_points = 595.0f,
    .height_points = 842.0f,
    .background_argb = 0xffffffffu
};
quantapdf_composer_text_options style = {
    .struct_size = sizeof(quantapdf_composer_text_options),
    .font = QUANTAPDF_COMPOSER_FONT_HELVETICA,
    .font_size = 12.0f,
    .argb = 0xff202020u,
    .line_height_multiplier = 1.2f,
    .alignment = QUANTAPDF_COMPOSER_TEXT_ALIGN_LEFT,
    .wrap = 1
};
quantapdf_rect text_box = { 36.0f, 36.0f, 559.0f, 180.0f };

if (quantapdf_composer_create(NULL, &composer) == QUANTAPDF_OK &&
    quantapdf_composer_add_page(composer, &page, &page_index) ==
        QUANTAPDF_OK &&
    quantapdf_composer_draw_text(
        composer, page_index, "Hello QuantaPDF", &text_box, &style) ==
        QUANTAPDF_OK &&
    quantapdf_composer_finish(composer, &output) == QUANTAPDF_OK) {
    quantapdf_output_save_file(output, "created.pdf");
}
quantapdf_drop_output(output);
quantapdf_drop_composer(composer);
```

Register JPEG or PNG bytes once with `quantapdf_composer_add_image()`, then
place the returned nonzero image ID with `quantapdf_composer_draw_image()`.
The fit policy can contain, cover (with clipping), or stretch the image.
Opaque 8-bit RGB PNG and 8-bit RGBA PNG are supported; PNG alpha is preserved
as a PDF soft mask. JPEG supports baseline 8-bit gray and RGB images;
progressive JPEG is rejected before decode to preserve the configured memory
bound.

V1 text accepts UTF-8 input that is representable by WinAnsi and the 12
Helvetica/Times/Courier base-14 variants. Invalid UTF-8 or unrepresentable
code points fail explicitly. Complex-script shaping and embedded TTF/OTF fonts
are intentionally reserved for an additive future API; V1 never substitutes
missing glyphs silently.

The default capacity is 1,024 pages, 1,000,000 draw operations, and 256 MiB for
owned text/image resources and bounded image-decoder working memory. Supply
`quantapdf_composer_options` to lower or raise those limits. Crossing a
configured limit returns
`QUANTAPDF_ERROR_UNSUPPORTED` without partially publishing the operation.

## Rendering

The convenience call:

```c
quantapdf_render_page(page, &bitmap);
```

renders the full page at 72 DPI, zero additional rotation, opaque DeviceRGB, and a white background.

For explicit rendering use a versioned options struct:

```c
quantapdf_render_options options = {
    sizeof(quantapdf_render_options),
    144.0f, /* dpi */
    0.0f,   /* rotation_degrees */
    0,      /* clip_enabled */
    { 0 },  /* clip in displayed page space */
    0       /* alpha */
};

quantapdf_render_page_with_options(page, &options, &bitmap);
```

`struct_size` is part of the ABI contract. Callers should initialize it to the size of the struct they compiled against. Render options are a single append-only structure; the library ignores fields beyond the caller-provided size so older binaries retain their original defaults.

`dpi` is the canonical zoom/resolution input: 72 DPI is scale 1.0, 144 DPI is scale 2.0. Rotation is in degrees and is applied only to that render call. When clipping is enabled, `clip` is expressed in displayed page space and is transformed by the same DPI/rotation matrix; QuantaPDF renders directly into the clipped device bbox rather than allocating a full-page intermediate image.

`alpha` accepts only 0 or 1:

- `0`: 8-bit interleaved RGB, opaque white untouched pixels;
- `1`: 8-bit interleaved RGBA, transparent untouched pixels.

RGBA samples produced by the renderer use **premultiplied alpha**. `stride` returned by `quantapdf_bitmap_dimensions` is the authoritative byte distance between rows; callers must not assume a different packing rule. The pointer returned by `quantapdf_bitmap_data` is borrowed read-only storage and remains valid only until `quantapdf_drop_bitmap`.

## Thumbnails

```c
quantapdf_render_thumbnail(page, max_width, max_height, &bitmap);
```

renders opaque RGB while preserving the page aspect ratio. The result fits inside the requested pixel box and never upscales beyond the page's 72-DPI size. Thumbnail rendering derives a DPI and reuses the same renderer rather than maintaining a separate raster path.

## Document audit and sanitization

Initialize the size-tagged audit result before calling the audit API, then test
the independent finding bits that matter to your policy:

```c
quantapdf_audit_result audit = {
    .struct_size = sizeof(quantapdf_audit_result),
    .findings = 0
};

if (quantapdf_document_audit(doc, &audit) == QUANTAPDF_OK) {
    if (audit.findings & QUANTAPDF_AUDIT_JAVASCRIPT_ACTION) {
        /* JavaScript action or JavaScript name tree is reachable. */
    }
    if (audit.findings & QUANTAPDF_AUDIT_SIGNATURE) {
        /* A signature structure is present; validity is not checked. */
    }
    if (audit.findings & QUANTAPDF_AUDIT_ENCRYPTION) {
        /* The input is encrypted, even if it was opened with a password. */
    }
}
```

Sanitization returns a new immutable output and never mutates the opened
document:

```c
quantapdf_output *output = NULL;

if (quantapdf_sanitize(doc, QUANTAPDF_SANITIZE_ALL, &output) ==
    QUANTAPDF_OK) {
    const unsigned char *data = NULL;
    size_t size = 0;

quantapdf_output_data(output, &data, &size);
    /* data[0..size) is borrowed read-only storage owned by output. */

quantapdf_close(doc);
    doc = NULL;
    /* data remains valid because output owns its bytes independently. */

quantapdf_drop_output(output);
}
```

`QUANTAPDF_SANITIZE_ALL` removes the seven sanitizable active-content classes.
Safe internal `/GoTo` navigation is not reported as dangerous and is not
removed. Signed or encrypted inputs are intentionally rejected by
`quantapdf_sanitize()` with `QUANTAPDF_ERROR_UNSUPPORTED` because rewriting
would invalidate a signature or silently decrypt the document.

The audit is a strict, catalog-reachable structural inspection of conventional
PDF security and active-content mechanisms. It is not antivirus or malware
detection, content keyword scanning, cryptographic signature validation, or
proof that arbitrary custom object edges are safe. Malformed conventional
structures return `QUANTAPDF_ERROR_FORMAT`; a bounded traversal or a requested
removal that cannot be proven complete returns `QUANTAPDF_ERROR_UNSUPPORTED`
without publishing output.

## PDF security rewrite

Security changes are explicit immutable transforms. V1 writes only the PDF
Standard Security Handler revision 6 with AES-256; decrypt and re-encrypt
accept encrypted documents that `quantapdf_open()` has already authenticated.
Signed inputs are rejected because a full rewrite would invalidate signatures.

```c
quantapdf_encryption_options security = {
    .struct_size = QUANTAPDF_ENCRYPTION_OPTIONS_V1_SIZE,
    .method = QUANTAPDF_ENCRYPTION_AES_256,
    .user_password_utf8 = "reader",
    .owner_password_utf8 = "document-owner",
    .permissions = QUANTAPDF_PERMISSION_COPY |
        QUANTAPDF_PERMISSION_PRINT_LOW_RESOLUTION,
    .encrypt_metadata = 1
};
quantapdf_output *encrypted = NULL;

if (quantapdf_encrypt_pdf(doc, &security, &encrypted) == QUANTAPDF_OK) {
    quantapdf_output_save_file(encrypted, "encrypted.pdf");
    quantapdf_drop_output(encrypted);
}
```

V1 passwords are NUL-terminated preparation-invariant printable ASCII
(`0x20..0x7e`) with a maximum of 127 bytes. The user password may be empty;
the owner password must be nonempty and distinct. No password is truncated.
The field names retain the `_utf8` suffix because printable ASCII is a strict
UTF-8 subset; arbitrary Unicode passwords are intentionally deferred until a
standards-compliant preparation dependency is available.

Permissions are advisory viewer hints, not DRM. High-quality printing requires
the low-resolution print bit. `ANNOTATE_AND_FILL_FORMS` reflects PDF bit 6,
which permits both annotation changes and filling existing fields;
`FILL_FORMS` controls the independent PDF bit 9. Accessibility extraction is
always available for R6 and therefore has no misleading public toggle.

Encryption and re-encryption intentionally produce different bytes on repeated
calls. QuantaPDF supplies qpdf with OS-backed cryptographic randomness and
generates fresh security material. Decryption is deterministic for identical
authenticated input. Every result owns its bytes independently of the source:

```c
quantapdf_document *authenticated = NULL;
quantapdf_output *plaintext = NULL;

if (quantapdf_open("encrypted.pdf", "reader", &authenticated) ==
        QUANTAPDF_OK &&
    quantapdf_decrypt_pdf(authenticated, &plaintext) == QUANTAPDF_OK) {
    quantapdf_output_save_file(plaintext, "plaintext.pdf");
}
quantapdf_drop_output(plaintext);
quantapdf_close(authenticated);
```

To edit an encrypted document, decrypt it, save and reopen the plaintext,
perform the desired explicit transforms, then encrypt the final document.
Existing save, crop, trim, flatten, recompress, rewrite, edit, and Composer
operations never add, remove, or replace encryption implicitly.

Shared builds isolate the private qpdf provider. In a static-link process,
replacing qpdf's process-global provider after QuantaPDF initializes causes
encrypt and re-encrypt to fail `QUANTAPDF_ERROR_UNSUPPORTED`; QuantaPDF never
temporarily overrides or restores the consumer's pointer.

## Lossless rewrite and garbage collection

```c
quantapdf_output *rewritten = NULL;

if (quantapdf_rewrite_lossless(doc, &rewritten) == QUANTAPDF_OK) {
    quantapdf_output_save_file(rewritten, "canonical.pdf");
    quantapdf_drop_output(rewritten);
}
```

`quantapdf_rewrite_lossless()` performs a deterministic full rewrite with a
fixed policy. It removes indirect objects unreachable from the trailer graph,
rebuilds the cross-reference state, preserves existing stream encodings, and
does not deduplicate distinct reachable objects. Repeated calls on identical
input—and rewriting a reopened result—produce byte-identical output.

This API is deliberately strict. It does not repair damaged PDFs, recompress
images, or flatten interactive content. It neither preserves nor creates
encryption: encrypted input is rejected with `QUANTAPDF_ERROR_UNSUPPORTED`.
Inputs requiring structural recovery return `QUANTAPDF_ERROR_FORMAT`, and
already signed inputs return `QUANTAPDF_ERROR_UNSUPPORTED`. The returned
output owns its bytes independently of the source document.

## Image recompression

Image recompression is an explicit lossy transform that returns a new owning
output and leaves the opened document unchanged:

```c
quantapdf_image_recompression_options options = {
    .struct_size = sizeof(quantapdf_image_recompression_options),
    .jpeg_quality = 90,
    .max_decoded_bytes_per_image =
        QUANTAPDF_IMAGE_RECOMPRESSION_DEFAULT_MAX_DECODED_BYTES
};
quantapdf_output *recompressed = NULL;

if (quantapdf_recompress_images(doc, &options, &recompressed) ==
    QUANTAPDF_OK) {
    quantapdf_output_save_file(recompressed, "recompressed.pdf");
    quantapdf_close(doc);
    doc = NULL;
    /* recompressed remains valid after its source document is closed. */
    quantapdf_drop_output(recompressed);
}
```

V1 rewrites only reachable, opaque, indirect 8-bit `DeviceGray` and
`DeviceRGB` Image XObjects whose decoded byte count fits the caller's cap.
The default cap is 64 MiB per image. Shared images keep one object identity
and are encoded once; nested Form resources and annotation/Widget appearance
resources are included. Valid unsupported images—including CMYK, ICCBased,
Indexed, masked, non-8-bit, and non-identity-Decode images—are preserved.

`jpeg_quality` accepts 1 through 100. Quality 100 still performs JPEG
encoding and is not a no-op. This API does not resize or downsample images,
rewrite inline images, flatten alpha, convert color spaces, preserve digital
signatures, or retain encryption. Signed and encrypted inputs fail with
`QUANTAPDF_ERROR_UNSUPPORTED`; malformed consumed image/resource structures
fail closed without publishing output.

## Flatten interactive content

```c
quantapdf_output *flattened = NULL;

if (quantapdf_flatten_interactive(
        doc,
        QUANTAPDF_FLATTEN_ANNOTATIONS | QUANTAPDF_FLATTEN_WIDGETS,
        &flattened) == QUANTAPDF_OK) {
    quantapdf_output_save_file(flattened, "flattened.pdf");
    quantapdf_drop_output(flattened);
}
```

`quantapdf_flatten_interactive()` bakes existing normal appearance streams
into page content. Annotation and Widget selection are independent flags, and
the source document remains immutable. Widget flattening also prunes the
affected AcroForm field tree and calculation order.

The transform never synthesizes appearances, applies redactions, executes
form actions, or flattens Links. It fails closed for missing or malformed
appearances, malformed or unbalanced changed-page content, non-unit annotation
opacity, contradictory Widget page ownership, unsupported interactive
semantics, visible Links on changed pages, tagged PDFs that require structure
updates, encryption, and signatures.
Output is deterministic and idempotent.

## Dependency model

The backend foundation has two pinned dependency paths:

- `cmake/QuantaPDFPdfium.cmake` downloads the exact platform PDFium artifact,
  verifies its SHA-256, version, disabled V8/XFA settings, and license payload,
  and rejects unsupported platforms.
- `vcpkg.json` resolves qpdf `12.4.0` from the pinned registry baseline with
  optional OpenSSL, GnuTLS, and Zopfli features disabled.
- PDFium and qpdf remain private implementation dependencies; only the
  `quantapdf_*` C ABI is public.

The target architecture is:

```text
PDFium public C API ----+
                       +--> QuantaPDF private adapters --> quantapdf_* C ABI
qpdf C++ object graph --+
```

Only the `quantapdf_*` ABI is exported by the wrapper.

## Build with CMake Presets and vcpkg

Set `PROJECT_ROOT` to the parent package workspace and `VCPKG_ROOT` to a
vcpkg checkout containing the baseline in `vcpkg.json`. The configure presets
run manifest installation automatically. Public
configure, build, and test entry points live in the versioned
`CMakeUserPresets.json`.

### Linux x64

```sh
export PROJECT_ROOT=/opt
export VCPKG_ROOT=/opt/vcpkg

cmake --fresh --preset linux-release-user
cmake --build --preset linux-release-user
ctest --preset linux-release-user
```

### macOS

Use `macos-arm64-release-user` on Apple Silicon or
`macos-x64-release-user` on Intel, then run the same configure, build, and
CTest preset sequence.

### Windows x64 DLL

Run from an x64 Visual Studio Developer Command Prompt so `cl`, Ninja, and
the MSVC runtime are available:

```bat
set PROJECT_ROOT=C:\projects\cpp
set VCPKG_ROOT=C:\tools\vcpkg

cmake --fresh --preset win-release-user
cmake --build --preset win-release-user
ctest --preset win-release-user
```

Use `win-dev-user` for the isolated Debug + AddressSanitizer profile.

The test build stages `quantapdf.dll` beside every Windows test executable. Consumers are responsible for deploying `quantapdf.dll` beside their executable or otherwise making it available through normal Windows DLL search rules.

## Tests

CTest covers the document lifecycle plus Page + Render contracts, including invalid arguments, page geometry, MediaBox/CropBox coordinates, RGB/RGBA output, versioned render options, DPI, rotation, clipping, thumbnails, encrypted PDFs, malformed input, repeated lifecycle stress, interleaved handles, UTF-8 paths, deterministic lossless rewrite/GC, and strict interactive-content flattening.

Linux additionally runs AddressSanitizer and UndefinedBehaviorSanitizer.

## CI

Normal pull-request updates use Linux as the fast development loop. Windows and macOS are reserved for explicit `full-ci` checkpoints, manual workflow dispatch, and pushes to `master`.

The workflow persists vcpkg binary packages and the exact hash-verified PDFium
archive. Cache identities include OS/architecture, the pinned vcpkg commit,
manifest content, and literal PDFium release `chromium-8021`.

A feature is not considered cross-platform complete until Linux, macOS, and Windows pass on the same exact head SHA. Older green runs do not satisfy acceptance for a newer head.

## License

QuantaPDF source is distributed under the **Apache License 2.0**. See
`LICENSE` and `THIRD_PARTY.md`.

The PDFium and qpdf backend dependencies use permissive licenses. Their pinned
license payloads and redistribution notices are installed with QuantaPDF; see
`THIRD_PARTY.md` for details.

QuantaPDF

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

QuantaPDF

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README