% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_pdf_text.R
\name{get_pdf_text}
\alias{get_pdf_text}
\title{Obtain Text from a PDF Document}
\usage{
get_pdf_text(
  input,
  output = tempfile(fileext = ".txt"),
  dpi = 300,
  psm = 1,
  force_ocr = FALSE,
  preprocess = FALSE,
  min_chars = 20,
  cores = NULL,
  timeout = 120
)
}
\arguments{
\item{input}{'character' string.
File path to the PDF document.}

\item{output}{'character' string.
File path for the text file to write. If the path lacks a \code{.txt} or \code{.text}
extension, \code{.txt} is appended. Defaults to a temporary file.}

\item{dpi}{'integer' number between 100 and 1200.
Resolution, in dots per inch, at which pages are rendered before OCR.
Higher values improve OCR accuracy at the cost of speed; 300 (the default)
suits most documents, while 400 to 600 may help with small fonts or poor
scans. Ignored for pages read directly from the text layer.}

\item{psm}{'integer' number between 0 and 13.
Tesseract Page Segmentation Mode, describing the expected page layout.
The default of 1 segments the page automatically and detects orientation and
script, which suits multi-column documents.}

\item{force_ocr}{'logical' flag.
Whether to OCR every page regardless of its text layer. Use this when the
embedded text is known to be unreliable (e.g. fonts that extract as gibberish,
which \code{min_chars} cannot catch because the gibberish is long enough to pass).
Defaults to \code{FALSE}.}

\item{preprocess}{'logical' flag.
Whether to grayscale, deskew, despeckle, and normalize each page image before
OCR, which improves accuracy on scanned documents at a modest per-page cost.
Requires the \pkg{magick} package. Applies only to pages that are OCR'd.
Defaults to \code{FALSE}.}

\item{min_chars}{'integer' number.
Minimum number of non-whitespace characters a page's extracted text must
have to be accepted without OCR. Pages below this threshold are sent to OCR.
Defaults to 20.}

\item{cores}{'integer' number.
Number of parallel workers to use for OCR. When \code{NULL} (the default), the
count is taken from the \code{OCR_CORES} environment variable if set (useful for
honoring a container CPU quota), otherwise from one fewer than the number of
detected cores.}

\item{timeout}{'numeric' number.
Maximum time, in seconds, to allow each child-process call to run before it
is aborted. Applied independently to the text-extraction call and the
page-rendering call. Defaults to 120.}
}
\value{
Returns the path to the text file, invisibly.
Each page of the PDF is written as a separate line.
}
\description{
Extract text from a PDF document and write it to a plain-text
file, one page per line. Pages with an extractable text layer are read
directly; pages without one (e.g. scanned images) fall back to optical
character recognition (OCR). The text is normalized to ASCII before writing.

Requires the \pkg{pdftools}, \pkg{tesseract}, and \pkg{callr} packages;
image preprocessing additionally requires \pkg{magick}.
}
\details{
Direct extraction is attempted first, as it is faster and more accurate than
OCR for born-digital PDFs; a page is OCR'd only when its text layer yields
fewer than \code{min_chars} non-whitespace characters, or when \code{force_ocr} is
\code{TRUE}. Poppler reads and page rendering run in isolated child processes, so
a renderer crash surfaces as a normal R error rather than aborting the
session.

Directly extracted text is reordered into human reading order from word
bounding boxes: full-width headers and captions are set aside, then the body
is split into columns only on strong evidence of a multi-column layout. OCR
uses Tesseract's LSTM engine, run in parallel across \code{cores} workers when
several pages need it. The result is normalized to strictly ASCII: selected
scientific symbols become ASCII tokens, accents are transliterated, line-break
hyphenation is rejoined, and quotes, control characters, and repeated
punctuation and whitespace are cleaned up.
}
\examples{
\dontrun{
  input <- system.file("extdata", "test.pdf", package = "inlpubs")
  path <- get_pdf_text(input)

  unlink(path)
}
}
\seealso{
\code{\link{add_content}} to add extracted text to the \pkg{inlpubs}-package corpus.
}
\author{
J.C. Fisher, U.S. Geological Survey, Idaho Water Science Center
}
