NativeElixirPdfUtilities.Stamp (native_elixir_pdf_utilities v0.18.0)

View Source

Adds text, watermarks, page numbers, and PDF-page overlays to existing PDFs.

Stamp page selections are one-based. Coordinates use the displayed page after CropBox, rotation, and UserUnit are applied. The origin is at the top-left, X increases rightward, and Y increases downward. Named positions and explicit {x, y} positions use PDF points in that coordinate system.

Successful operations append an incremental revision. Existing document bytes, metadata, outlines, forms, and unselected page objects remain intact. PDF overlays import page artwork only; annotations, outlines, metadata, and interactive forms from the overlay PDF are not copied.

Summary

Types

error_reason()
overlay_option()
page_selector()
position()
text_option()

Functions

overlay(pdf, overlay_pdf, options \\ [])

Adds page artwork from another PDF over all or selected target pages.

page_numbers(pdf, options \\ [])

Adds formatted page numbers to all or selected pages.

text(pdf, text, options \\ [])

Adds one text stamp to all or selected pages.

watermark(pdf, text, options \\ [])

Adds a centered, diagonal, translucent text watermark.

Types

error_reason()

@type error_reason() ::
  :encrypted_pdf
  | :invalid_options
  | :invalid_page_selection
  | :invalid_pdf_input
  | :invalid_stamp
  | :page_out_of_bounds
  | :resource_limit_exceeded
  | :unsupported_glyph
  | :unsupported_pdf_feature

overlay_option()

@type overlay_option() ::
  {:pages, :all | [page_selector()]}
  | {:overlay_pages, :match | {:repeat, pos_integer()}}
  | {:fit, :exact | :contain | :cover | :stretch}
  | {:opacity, number()}

page_selector()

@type page_selector() :: pos_integer() | Range.t()

position()

@type position() ::
  :top_left
  | :top_center
  | :top_right
  | :center_left
  | :center
  | :center_right
  | :bottom_left
  | :bottom_center
  | :bottom_right
  | {number(), number()}

text_option()

@type text_option() ::
  {:pages, :all | [page_selector()]}
  | {:position, position()}
  | {:margin, non_neg_integer() | float()}
  | {:font, String.t()}
  | {:fonts, [map() | keyword() | {String.t(), String.t()}]}
  | {:font_weight, 100..900}
  | {:font_style, :normal | :italic}
  | {:size, :auto | number()}
  | {:color, {number(), number(), number()}}
  | {:opacity, number()}
  | {:rotation, number()}
  | {:system_font_discovery, boolean()}

Functions

overlay(pdf, overlay_pdf, options \\ [])

@spec overlay(binary(), binary(), [overlay_option()]) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Adds page artwork from another PDF over all or selected target pages.

overlay_pages: {:repeat, page} repeats one overlay page and is the default with page one. overlay_pages: :match maps overlay pages to selected target pages in order and requires equal counts. fit: :exact is the default; :contain, :cover, and :stretch opt into scaling.

page_numbers(pdf, options \\ [])

@spec page_numbers(binary(), [
  text_option() | {:format, String.t()} | {:numbering, :document | :selection}
]) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Adds formatted page numbers to all or selected pages.

The format supports {{page}} and {{pages}}. numbering: :document uses physical document page numbers and is the default. numbering: :selection numbers only selected pages. Text options configure position, font, size, color, opacity, and rotation.

text(pdf, text, options \\ [])

@spec text(binary(), String.t(), [text_option()]) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Adds one text stamp to all or selected pages.

The default position is :center. The bundled DejaVu Sans face is used unless another family and matching :fonts configuration are supplied.

watermark(pdf, text, options \\ [])

@spec watermark(binary(), String.t(), [text_option()]) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Adds a centered, diagonal, translucent text watermark.

Watermarks default to an automatically fitted size, 15 percent opacity, and 45 degrees clockwise rotation. Any text-stamp option can override a default.