#lang scribble/doc @(require scribble/manual planet/scribble (for-label racket) (for-label racket/gui) (for-label slideshow/pict) (for-label (this-package-in main))) @title{@bold{pdf-render}: Render and parse PDF files} @author{gcr, based on code by Jens Axel Søgaard} @defmodule/this-package[main]{ This library lets Racket render PDF files. You can also gather information about the text or layout. This requires @tt{libpoppler}, and thus likely only works on Linux or Mac OSX. Windows might work if you insctall Poppler, but I can't make promises. } @table-of-contents[] @section{Examples} Showing a PDF as a pict is as easy as you'd expect: @codeblock{ #lang racket (require slideshow/pict (planet gcr/pdf-render)) (show-pict (page->pict "oopsla04-gff.pdf")) } @image{imgs/pageone.png} By default, @racket[page->pict] shows the first page of the given PDF filename. You can also say something like @racket[(show-pict (page->pict (pdf-page "oopsla04-gff.pdf" 5)))] to show the 4th page (pages are zero-indexed). You can also search for text. This snippet searches for every occurance of the word "the" and overlays a yellow rectangle on each: @codeblock{ ;; The first page of a PDF file. (Pages are zero-indexed) (define page (pdf-page "oopsla04-gff.pdf" 0)) ;; Overlay each box over the PDF. (for/fold ([pageview (page->pict page)]) ([bounding-box (in-list (page-find-text page "the"))]) (match-define (list x1 y1 x2 y2) bounding-box) ;; Each match's bounding box ^ (pin-over pageview x1 y1 (cellophane (colorize (filled-rectangle (- x2 x1) (- y2 y1)) "yellow") 0.5))) } @image{imgs/search.png} Finally, for low-level layout control, you can gather the bounding box geometry for each letter on the page. This snippet outlines each letter's bounding box. @codeblock{ (define page (pdf-page "oopsla04-gff.pdf" 0)) (for/fold ([pageview (apply blank (page-size page))]) ([box (in-list (page-text-layout page))]) (match-define (list x1 y1 x2 y2) box) (pin-over pageview x1 y1 (colorize (rectangle (- x2 x1) (- y2 y1)) "gray"))) } @image{imgs/text.png} Note that @racket[page->pict] does not convert the file to a bitmap. You can rotate, scale, or transform the resulting pict however you like without losing quality. @codeblock{ (rotate (frame (scale (inset/clip (page->pict page) -400 -300 -100 -400) 5)) (* 0.125 pi)) } @image{imgs/rotated.png} If you want to coerce the result to a bitmap for speed, you can do that as well: @codeblock{ (rotate (frame (scale (inset/clip (bitmap (page->bitmap page)) -400 -300 -100 -400) 5)) (* 0.125 pi)) } @image{imgs/rotated-bitmap.png} @section{PDF files} All functions that accept pages or documents also accept filenames. This is more convenient for you, but it is also less efficient because the document must be re-opened every time. You can make this faster by keeping the result of @racket[pdf-page] or @racket[open-pdf-uri] to ensure that this library only opens the document once. @defproc[(pdf-document? [maybe-doc any/c]) boolean?]{ Returns @racket[#t] if @racket[maybe-doc] is a PDF document. This can be a string (filename) or the result of @racket[open-pdf-uri]. } @defproc[(open-pdf-uri [uri string?] [password (or/c string? false?)]) (or/c pdf-document? false?)]{ Opens the given PDF file with the given uri and the given password. The @racket[password] may be @racket[#f] if the document does not have a password. The @racket[uri] is usually something like @racket["file:/tmp/test.pdf"]; anything libpoppler accepts. Don't forget the @tt{file:} at the beginning for local documents! This function will throw an error if the PDF file does not exist. For example, if you wish to show the tenth page from an encrypted document, use: @codeblock{ (define document (open-pdf-uri "file:/tmp/secret.pdf" "some_password")) (define page (pdf-page document 9)) (show-pict (page->pict page)) } } As a shortcut, @racket[(page->pict "/tmp/filename.pdf")] is a shortcut for @codeblock{ (page->pict (pdf-page (open-pdf-uri "file:/tmp/filename.pdf" #f) 0)) } Most of these functinos honor shortcuts like this. @defproc[(pdf-page? [maybe-page any/c]) boolean?]{ Returns true if @racket[maybe-page] is a page. Pages can be filenames (in which case the first page of the document will be used), @racket[pdf-document?]s, or the result of @racket[pdf-page]. } @defproc[(pdf-page [maybe-doc pdf-document?] [page-index exact-nonnegative-integer?]) pdf-page?]{ Opens the @racket[page-index]th page in @racket[maybe-doc]. Pages are zero-indexed, so if you want the third page of @racket["/tmp/oopsla04-gff.pdf"], for example, use: @racketblock[(pdf-page "/tmp/oopsla04-gff.pdf" 2)] } @section{Rendering} @defproc[(page->pict [page pdf-page?]) pict?]{ Renders the given @racket[page] to a @racket[pict] from Racket's @racket[slideshow/pict] library. This pict can be transformed any way you like without rasterization. } @defproc[(page->bitmap [page pdf-page?]) (is-a?/c bitmap%)]{ Renders the @racket[page] at 72 DPI to a @racket[bitmap%]. } @defproc[(page-render-to-dc! [page pdf-page?] [dc (is-a?/c dc<%>)]) any/c]{ Renders the given @racket[page] to the given @racket[dc<%>] context. This only works if @racket[dc] is backed by Cairo and the moons are aligned properly. } @defproc[(page-render-to-cairo! [page pdf-page?] [_cairo_t any/c]) any/c]{ Render the given @racket[page] to the given @racket[_cairo_t] Cairo context with the current transformation. } @section{Layout} @defproc[(page-size [page pdf-page?]) (list/c (and/c real? (not/c negative?)) (and/c real? (not/c negative?)))]{ Returns the width and height of @racket[page], in points (1/72 of an inch). } @defproc[(page-crop-box [page pdf-page?]) (list/c (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)))]{ Returns the rectangle of @racket[page]'s crop box. Each rectangle is a @racket[(list x1 y1 x2 y2)], where @tt{x1,y1} is the top left corner and @tt{x2,y2} is the bottom right. Coordinates are in points (1/72 of an inch). } @defproc[(page-text-in-rect [page pdf-page?] [mode (one-of/c 'glyph 'word 'line)] [x1 (and/c inexact? (not/c negative?))] [y1 (and/c inexact? (not/c negative?))] [x2 (and/c inexact? (not/c negative?))] [y2 (and/c inexact? (not/c negative?))]) string?]{ Returns the string inside the given rectangle. If @racket[mode] is @racket['glyph], the closest-matching characters are returned; if @racket[mode] is @racket['word], the returned string will be the words lying in the rectangle; if @racket[mode] is @racket['line], an entire line of text will be returned. When specifying the rectangle, @tt{x1,y1} should be the top left corner and @tt{x2,y2} should be the bottom right. Coordinates are in points (1/72 of an inch). } @defproc[(page-text [page pdf-page?]) string?]{ Returns all the text in @racket[page] as a string. } @defproc[(page-text-layout [page pdf-page?]) (listof (list/c (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?))))]{ Returns bounding boxes for each of the letters in @racket[page]. The poppler documentation says that the @racket[N]th character in @racket[(page-text page)] should correspond with the @racket[N]th bounding box, but this may or may not be accurate. Each bounding box is a @racket[(list x1 y1 x2 y2)], where @tt{x1,y1} is the top left corner and @tt{x2,y2} is the bottom right. Coordinates are in points (1/72 of an inch). } @defproc[(page-text-with-layout [page pdf-page?]) (listof (list/c string (list/c (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)))))]{ Returns each letter in the document along with its bounding box for each of the letters in @racket[page]. Note that each letter's string may be longer than one letter, and it often includes newlines. Each bounding box is a @racket[(list x1 y1 x2 y2)], where @tt{x1,y1} is the top left corner and @tt{x2,y2} is the bottom right. Coordinates are in points (1/72 of an inch). For example, @codeblock{ (take (page-text-with-layout "oopsla04-gff.pdf") 5) } will return the bounding boxes of the first five letters on the first page of @racket["oopsla04-gff.pdf"], namely: @codeblock{ '(("S\n" (150.738 71.302 162.699 87.890)) ("u\n" (162.699 71.302 173.656 87.890)) ("p\n" (173.656 71.302 184.613 87.890)) ("e\n" (184.613 71.302 194.584 87.890)) ("r\n" (194.584 71.302 201.560 87.890))) } } @section{Searching} @defproc[(page-find-text [page pdf-page?] [text string?]) (listof (list/c (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?))))]{ Searches for the given @racket[text] on @racket[page]. This is a case-insensitive search. Returns a list of rectangle coordinates. Each rectangle is a @racket[(list x1 y1 x2 y2)], where @tt{x1,y1} is the top left corner and @tt{x2,y2} is the bottom right. Coordinates are in points (1/72 of an inch). } @section{Metadata} @defproc[(pdf-count-pages [doc pdf-document?]) exact-nonnegative-integer?]{ Returns the number of pages in @racket[doc]. } @defproc*[( [(pdf-title [doc pdf-document?]) (or/c false? string?)] [(pdf-author [doc pdf-document?]) (or/c false? string?)] [(pdf-subject [doc pdf-document?]) (or/c false? string?)] [(pdf-keywords [doc pdf-document?]) (or/c false? string?)] [(pdf-creator [doc pdf-document?]) (or/c false? string?)] [(pdf-producer [doc pdf-document?]) (or/c false? string?)])]{ Returns metadata about @racket[doc]. } @defproc[(page-label [page pdf-page?]) (or/c false? string?)]{ Returns the @racket[page]'s "label", which is often a numeral like @racket["1"] or @racket["2"], but it may be a Roman numeral like @racket["xii"] for certain sections of the PDF. It may even be some other exotic name like @racket["Table of Contents"]. } @section{Bugs and Issues} Note that @racket[pdf->pict] draws directly to the underlying surface's cairo context. This may have problems if the @racket[dc<%>] is not backed by cairo or if you perform different transformations (like cropping or blurring).