Mutool is a collection of useful command line utilities rolled into a single executable.
As explained earlier MuPDF is a C library that encapsulates all the smarts required to open/render/manipulate document files of a range of a formats. This means that most utilities using it are reduced to very thin shells that just call down to the library.
When you consider the additional factor of the size of the resources built into MuPDF (fonts, CMAPs etc), this means it makes a lot of sense to build a single executable with multiple utilities sharing a single copy of the library.
If you run mutool at the command line with no arguments,
a list of the possible options will be displayed:
$ mutool
usage: mutool <command> [options]
clean -- rewrite pdf file
convert -- convert document
create -- create pdf document
draw -- convert document
extract -- extract font and image resources
info -- show information about pdf resources
merge -- merge pages from multiple pdf sources into a new pdf
pages -- show information about pdf pages
portfolio -- manipulate PDF portfolios
poster -- split large page into many tiles
run -- run javascript
show -- show internal pdf objects
The clean utility will produce a cleaned version of an
input PDF. It can apply a range of different options, a full list of
which can be obtained by running mutool clean
with no options:
$ mutool clean
usage: mutool clean [options] input.pdf [output.pdf] [pages]
-p - password
-g garbage collect unused objects
-gg in addition to -g compact xref table
-ggg in addition to -gg merge duplicate objects
-gggg in addition to -ggg check streams for duplication
-l linearize PDF
-a ascii hex encode binary streams
-d decompress streams
-z deflate uncompressed streams
-f compress font streams
-i compress image streams
-s clean content streams
pages comma separated list of page numbers and ranges
The arguments here are fairly self explanatory, and usage is best explained with a few examples.
Firstly, and most simply, clean can be used to try to
repair broken files. Many PDF files found in the wild are broken -
sometimes because of having been corrupted, either by
transmission/archiving problems, but a disappointing amount by just
having been created by bad PDF writing software. Running a clean pass
will attempt to repair the files:
mutool clean in.pdf out.pdf
Individual pages (or page ranges) can be extracted from a PDF. For example:
mutool clean -gggg in.pdf out.pdf 1-10,12
That will extract the pages 1 to 10, and page 12 of
in.pdf and output it into a new out.pdf. The
-gggg options ensure that unused objects will be dropped
from the PDF.
An 8 page PDF might be rearranged into booklet form using:
mutool clean -gggg in.pdf out.pdf 8,1,7,2,6,3,5,4
Finally, a more exotic, but very common example; if someone reports a problem seen on page 4 of a given PDF, the following command will extract that page, and expand the content streams, without decompressing the images or the fonts:
mutool clean -difgggg in.pdf out.pdf 4
If this file still exhibits the same problem, it is generally far easier to debug through it than the original one was.
The convert utility performs a similar task to the
draw utility, using a different internal mechanism (the
document writer interface). Which is better for any given task is often
a matter of taste.
$ mutool convert
mutool convert version 1.11
Usage: mutool convert [options] file [pages]
-p - password
-A - number of bits of antialiasing (0 to 8)
-W - page width for EPUB layout
-H - page height for EPUB layout
-S - font size for EPUB layout
-U - file name of user stylesheet for EPUB layout
-X disable document styles for EPUB layout
-o - output file name (%d for page number)
-F - output format (default inferred from output file name)
png, pnm, pgm, ppm, pam, tga, pbm, pkm,
pdf, svg, cbz
-O - comma separated list of options for output format
pages comma separated list of page ranges (N=last page)
Common raster format output options:
rotate=N: rotate rendered pages N degrees counterclockwise
resolution=N: set both X and Y resolution in pixels per inch
x-resolution=N: X resolution of rendered pages in pixels per inch
y-resolution=N: Y resolution of rendered pages in pixels per inch
width=N: render pages to fit N pixels wide (ignore resolution option)
height=N: render pages to fit N pixels tall (ignore resolution option)
colorspace=(gray|rgb|cmyk): render using specified colorspace
alpha: render pages with alpha channel and transparent background
Structured text output options:
preserve-ligatures: do not expand all ligatures into constituent characters
preserve-whitespace: do not convert all whitespace characters into spaces
PDF output options:
decompress: decompress all streams (except compress-fonts/images)
compress: compress all streams
compress-fonts: compress embedded fonts
compress-images: compress images
ascii: ASCII hex encode binary streams
pretty: pretty-print objects with indentation
linearize: optimize for web browsers
sanitize: clean up graphics commands in content streams
garbage: garbage collect unused objects
or garbage=compact: ... and compact cross reference table
or garbage=deduplicate: ... and remove duplicate objects
SVG output options:
text=text: Emit text as <text> elements (inaccurate fonts).
text=path: Emit text as <path> elements (accurate fonts).
no-reuse-images: Do not reuse images using <symbol> definitions.
The create tool allows PDFs to generated from simple
text files full of pdf operator streams plus formatted comments.
$ mutool create
usage: mutool create [-o output.pdf] [-O options] page.txt [page2.txt ...]
-o - name of PDF file to create
-O - comma separated list of output options
page.txt content stream with annotations for creating resources
Content stream special commands:
%%MediaBox LLX LLY URX URY
%%Rotate Angle
%%Font Name Filename (or base 14 font name)
%%Image Name Filename
PDF output options:
decompress: decompress all streams (except compress-fonts/images)
compress: compress all streams
compress-fonts: compress embedded fonts
compress-images: compress images
ascii: ASCII hex encode binary streams
pretty: pretty-print objects with indentation
linearize: optimize for web browsers
sanitize: clean up graphics commands in content streams
garbage: garbage collect unused objects
or garbage=compact: ... and compact cross reference table
or garbage=deduplicate: ... and remove duplicate objects
The draw utility is the most commonly used tool, capable
of converting/rendering documents to a range of bitmap and vector
formats. It performs a similar task to the convert utility,
using a different set of internal mechanisms. Which is better for any
given task is often a matter of taste.
$ mutool draw
mudraw version 1.11
Usage: mudraw [options] file [pages]
-p - password
-o - output file name (%d for page number)
-F - output format (default inferred from output file name)
raster: png, tga, pnm, pam, pbm, pkm, pwg, pcl, ps
vector: svg, pdf, trace
text: txt, html, stext
-s - show extra information:
m - show memory use
t - show timings
f - show page features
5 - show md5 checksum of rendered image
-R - rotate clockwise (default: 0 degrees)
-r - resolution in dpi (default: 72)
-w - width (in pixels) (maximum width if -r is specified)
-h - height (in pixels) (maximum height if -r is specified)
-f - fit width and/or height exactly; ignore original aspect
ratio
-B - maximum band_height (pgm, ppm, pam, png output only)
-W - page width for EPUB layout
-H - page height for EPUB layout
-S - font size for EPUB layout
-U - file name of user stylesheet for EPUB layout
-X disable document styles for EPUB layout
-c - colorspace (mono, gray, grayalpha, rgb, rgba, cmyk,
cmykalpha)
-G - apply gamma correction
-I invert colors
-A - number of bits of antialiasing (0 to 8)
-A -/- number of bits of antialiasing (0 to 8) (graphics, text)
-l - minimum stroked line width (in pixels)
-D disable use of display list
-i ignore errors
-L low memory mode (avoid caching, clear objects after each
page)
-P parallel interpretation/rendering
-N disable ICC workflow ("N"o color management)
-O Control spot rendering
0 = No spot rendering
1 = Overprint simulation
2 = Full spot rendering
-y l List the layer configs to stderr
-y - Select layer config (by number)
-y -{,-}* Select layer config (by number), and toggle the
listed entries
pages comma separated list of page numbers and ranges
The extract utility extracts objects from PDF files.
This can be used to extract resources such as fonts, ICC profiles,
images etc.
$ mutool extract
usage: mutool extract [options] file.pdf [object numbers]
-p password
-r convert images to rgb
Run without any object numbers listed, it will extract all the resources it can find within the file to your local filesystem. It is best to run this in a clean directory!
Alternatively specific resources can be extracted by specifying the
PDF object numbers. These can be obtained by using the info
utility.
The info utility displays various different sets of
information on the contents of a PDF file.
$ mutool info
usage: mutool info [options] file.pdf [pages]
-p - password for decryption
-F list fonts
-I list images
-M list dimensions
-P list patterns
-S list shadings
-X list form and postscript xobjects
pages comma separated list of page numbers and ranges
The merge utility allows a new output PDF to be created
by combining pages (or ranges of pages) from a set of input pdfs.
$ mutool merge
usage: mutool merge [-o output.pdf] [-O options] input.pdf [pages] [input2.pdf] [pages2] ...
-o - name of PDF file to create
-O - comma separated list of output options
input.pdf name of input file from which to copy pages
pages comma separated list of page numbers and ranges
PDF output options:
decompress: decompress all streams (except compress-fonts/images)
compress: compress all streams
compress-fonts: compress embedded fonts
compress-images: compress images
ascii: ASCII hex encode binary streams
pretty: pretty-print objects with indentation
linearize: optimize for web browsers
sanitize: clean up graphics commands in content streams
garbage: garbage collect unused objects
or garbage=compact: ... and compact cross reference table
or garbage=deduplicate: ... and remove duplicate objects
The pages utility displays information on the different
pages (such as MediaBoxes, CropBoxes etc) of a PDF file.
$ mutool pages
usage: mutool pages [options] file.pdf [pages]
-p - password for decryption
pages comma separated list of page numbers and ranges
The portfolio utility is used to create or manipulate
PDF portfolios.
$ mutool portfolio
usage: mutool portfolio [options] portfolio.pdf [actions]
Options are:
-p - password
-o - output (defaults to input file)
-O - PDF output options (see mutool create)
Actions are:
t display a table listing the contents of the portfolio
x N <file>
extract Nth entry to <file>
a <file> <name>
add contents of <file> as an entry named <name>
For safety, only use ASCII characters in entry names for now.
The poster utility is used to subdivide pages within a
PDF so that they can be printed to a small format printer and then
pasted together to form a poster.
$ mutool poster
usage: mutool poster [options] input.pdf [output.pdf]
-p - password
-x x decimation factor
-y y decimation factor
Unlike the other utilities, invoking run with no
arguments will not get you a list of arguments, but will instead start
an interpreter waiting for your input. This interpreter expects to be
fed Javascript commands to be executed using MuJS.
The PDF bindings present within the Javascript environment allow many powerful operations to be scripted on PDF and other files.
The show command will display various sections of the
PDF file in printable format. This will primarily be of use to people
working with the internals of PDF files, but the outline
option provides a way to get the outlines (a.k.a. bookmarks) from a PDF
file at the command line.
$ mutool show
usage: mutool show [options] file.pdf [grep] [xref] [trailer] [pagetree] [outline] [object numbers]
-p - password
-o - output file
-b print streams as binary data
-e print encoded streams (don't decode)
The MuPDF API is designed to be a set of interlocking pieces that can be assembled together in many different ways to offer a powerful range of functionality. The cost of this versatility is that a certain amount of assembly is required.
For those people who would prefer a more encapsulated solution, we have a helper library, MuOfficeLib, that handles much of the
For a basic description of how to query a document for the specified presentation details, see . Given these details, the caller is still responsible for displaying (animating) the transition.
To help with this task, MuPDF provides a helper function that generate the required frame of the transition into the supplied target pixmap from supplied rendered pixmaps of the start/end of the transition:
/*
fz_generate_transition: Generate a frame of a transition.
tpix: Target pixmap
opix: Old pixmap
npix: New pixmap
time: Position within the transition (0 to 256)
trans: Transition details
Returns 1 if successfully generated a frame.
*/
int fz_generate_transition(fz_context *ctx, fz_pixmap *tpix, fz_pixmap *opix, fz_pixmap *npix, int time, fz_transition *trans);
This helper function is largely independent of the rest of MuPDF, and will be dropped from the library at link time if it is not used.
It is still the callers responsibility to drive this, to display the updated pixmaps, and to generate the time field as appropriate from the actual real clock values.
In order to implement tools such as MuTool, and helpers such as mu-office-lib, we needed a simple cross platform threading library. MuThreads is that library.
It is a very simple interface layer that gives a consistent implementation of Mutexes, Semaphores and Threads that builds both on pthreads and on Windows threads. More platforms may be added in the future.
The interface is described in a single header, ‘mupdf/helpers/mu-threads.h’, and should be self-evident.