Function: pdf-util-convert

pdf-util-convert is a natively compiled function defined in pdf-util.el.

Signature

(pdf-util-convert IN-FILE OUT-FILE &rest SPEC)

Documentation

Convert image IN-FILE to OUT-FILE according to SPEC.

IN-FILE should be the name of a file containing an image. Write the result to OUT-FILE. The extension of this filename usually determines the resulting image-type.

SPEC is a property list, specifying what the convert program should do with the image. All manipulations operate on a rectangle, see below.

SPEC may contain the following keys, respectively values.

:foreground Set foreground color for all following operations.

:background Dito, for the background color.

:commands A list of strings representing arguments to convert
for image manipulations. It may contain %-escape characters, as follows.

%f -- Expands to the foreground color.
%b -- Expands to the background color.
%g -- Expands to the geometry of the current rectangle, i.e. WxH+X+Y.
%x -- Expands to the left edge of rectangle.
%X -- Expands to the right edge of rectangle.
%y -- Expands to the top edge of rectangle.
%Y -- Expands to the bottom edge of rectangle.
%w -- Expands to the width of rectangle.
%h -- Expands to the height of rectangle.

Keep in mind, that every element of this list is seen by convert as a single argument.

:formats An alist of additional %-escapes. Every element
should be a cons (CHAR . STRING) or (CHAR . FUNCTION). In the first case, all occurrences of %-CHAR in the above commands will be replaced by STRING. In the second case FUNCTION is called with the current rectangle and it should return the replacement string.

:apply A list of rectangles ((LEFT TOP RIGHT BOT) ...) in
IN-FILE coordinates. Each such rectangle triggers one execution of the last commands given earlier in SPEC. E.g. a call like

  (pdf-util-convert
   image-file out-file
   :foreground "black"
   :background "white"
   :commands '("-fill" "%f" "-draw" "rectangle %x,%y,%X,%Y")
   :apply '((0 0 10 10) (10 10 20 20))
   :commands '("-fill" "%b" "-draw" "rectangle %x,%y,%X,%Y")
   :apply '((10 0 20 10) (0 10 10 20)))

would draw a 4x4 checkerboard pattern in the left corner of the image, while leaving the rest of it as it was.

Returns OUT-FILE.

See URL http://www.imagemagick.org/script/convert.php.

Source Code

;; Defined in /nix/store/63h5z2vmzn0mfavcxi2idi23g5xcgkbl-emacs-packages-deps/share/emacs/site-lisp/elpa/pdf-tools-20260102.1101/pdf-util.el
(defun pdf-util-convert (in-file out-file &rest spec)
  "Convert image IN-FILE to OUT-FILE according to SPEC.

IN-FILE should be the name of a file containing an image.  Write
the result to OUT-FILE.  The extension of this filename usually
determines the resulting image-type.

SPEC is a property list, specifying what the convert program
should do with the image.  All manipulations operate on a
rectangle, see below.

SPEC may contain the following keys, respectively values.

`:foreground' Set foreground color for all following operations.

`:background' Dito, for the background color.

`:commands' A list of strings representing arguments to convert
for image manipulations.  It may contain %-escape characters, as
follows.

%f -- Expands to the foreground color.
%b -- Expands to the background color.
%g -- Expands to the geometry of the current rectangle, i.e. WxH+X+Y.
%x -- Expands to the left edge of rectangle.
%X -- Expands to the right edge of rectangle.
%y -- Expands to the top edge of rectangle.
%Y -- Expands to the bottom edge of rectangle.
%w -- Expands to the width of rectangle.
%h -- Expands to the height of rectangle.

Keep in mind, that every element of this list is seen by convert
as a single argument.

`:formats' An alist of additional %-escapes.  Every element
should be a cons \(CHAR . STRING\) or \(CHAR . FUNCTION\).  In
the first case, all occurrences of %-CHAR in the above commands
will be replaced by STRING.  In the second case FUNCTION is
called with the current rectangle and it should return the
replacement string.

`:apply' A list of rectangles \(\(LEFT TOP RIGHT BOT\) ...\) in
IN-FILE coordinates. Each such rectangle triggers one execution
of the last commands given earlier in SPEC. E.g. a call like

  (pdf-util-convert
   image-file out-file
   :foreground \"black\"
   :background \"white\"
   :commands \\='(\"-fill\" \"%f\" \"-draw\" \"rectangle %x,%y,%X,%Y\")
   :apply \\='((0 0 10 10) (10 10 20 20))
   :commands \\='(\"-fill\" \"%b\" \"-draw\" \"rectangle %x,%y,%X,%Y\")
   :apply \\='((10 0 20 10) (0 10 10 20)))

would draw a 4x4 checkerboard pattern in the left corner of the
image, while leaving the rest of it as it was.

Returns OUT-FILE.

See url `http://www.imagemagick.org/script/convert.php'."
  (pdf-util-assert-convert-program)
  (let* ((cmds (pdf-util-convert--create-commands spec))
         (status (apply #'call-process
                        pdf-util-convert-program nil
                        (get-buffer-create "*pdf-util-convert-output*")
                        nil
                        `(,in-file ,@cmds ,out-file))))
    (unless (and (numberp status) (= 0 status))
      (error "The convert program exited with error status: %s" status))
    out-file))