# `PDFium.Toolbox`

Whole jobs built from `PDFium`. A job takes documents as paths or
`{:bytes, contents}`, opens and closes them itself, and answers with the
document it made as a binary.

# `extract_pages`

```elixir
@spec extract_pages(PDFium.source(), [non_neg_integer()]) ::
  {:ok, binary()} | {:error, atom()}
```

Writes the given pages, counted from zero and in the order asked for, as a
document of their own.

    {:ok, binary} = PDFium.Toolbox.extract_pages("contract.pdf", [0, 2])

# `flatten`

```elixir
@spec flatten(PDFium.source(), :display | :print, PDFium.security()) ::
  {:ok, binary()} | {:error, atom()}
```

Draws every annotation into the page it sits on and drops it.

    {:ok, binary} = PDFium.Toolbox.flatten("contract.pdf")
    {:ok, binary} = PDFium.Toolbox.flatten("contract.pdf", :print, :remove)

# `merge`

```elixir
@spec merge([PDFium.source()]) :: {:ok, binary()} | {:error, atom()}
```

Writes the documents as one, in the order given.

    {:ok, binary} = PDFium.Toolbox.merge(["contract.pdf", {:bytes, attachment}])

# `overlay`

```elixir
@spec overlay(PDFium.source(), PDFium.source()) :: {:ok, binary()} | {:error, atom()}
```

Draws each page of `overlay_source` over the page of `source` in the same
place, scaled to fit and centred. The two must have the same number of pages.

    {:ok, binary} = PDFium.Toolbox.overlay("contract.pdf", {:bytes, header_and_footer})

# `render_pages!`

```elixir
@spec render_pages!(PDFium.source(), pos_integer()) :: Enumerable.t()
```

Renders every page of `source` at `dpi`, one at a time as the stream is read,
each as `{pixels, width, height}` in RGBA. Raises when the document cannot be
opened.

    PDFium.Toolbox.render_pages!("contract.pdf", 150) |> Enum.map(&to_png/1)

# `stamp`

```elixir
@spec stamp(
  PDFium.source(),
  [{PDFium.source(), non_neg_integer()}],
  PDFium.security()
) ::
  {:ok, binary()} | {:error, atom()}
```

Draws overlays over pages of `source`, each scaled to fit and centred.

    {:ok, binary} = PDFium.Toolbox.stamp("contract.pdf", [{"signature.pdf", 2}])

A placement is `{overlay, page_index}`, pages counted from zero. An overlay
is drawn by its first page, and placements on one page stack in the order
given.

---

*Consult [api-reference.md](api-reference.md) for complete listing*