tclMuPdf is a porting of the MuPDF framework (see at mupdf.com ), for fast and high-quality rendering of PDF pages.
History
13-dec-2016 - Version 1.0b1 (beta) released. No support for MacOS
15-dec-2016 - Version 1.0 - Support for MacOS. API unchanged, but big internal optimization for reusing opened pages (read
28-jan-2017 - Version 1.1 (Withdrawn) - new commands: fields, field, anchor, mupdf::libinfo . Added package mupdf-notk for tcl-only usage. (read the documentation). Aligned with core library MuPDF v.1.10a
23-feb-2017 - Version 1.2 (Withdrawn) with a lot of new features:
commands for extracting and searching text
commands for extracting images from PDF pages (experimental)
first steps towards PDF manipulations: you can add new signature fields, then save your changes.
many minor auxiliary commands
26-feb-2017 - Version 1.2.1 - BugFixing - replaces Version 1.1 and 1.2
a bug related to the saveImage command, introduced in 1.1 was fixed here.
Versions 1.1 and 1.2 were withdrawn
29-sep-2017 - Version 1.3 - image extraction
subcommands for extracting images, previously released as experimental.images are now official, more powerful and deeply tested with a lot of different kinds of images.
Aligned with core library MuPDF v.1.11
29-oct-2017 - Version 1.4 - portfolio & password-protected files
commands for working with PDF-portfolio (embedded files)
ability to work with password-protected PDFs.
BUG-FIX removed limit to 130 char for extracting images (full path name length)
20-Dec-2018 - Version 1.5 - field get&set, new export options, graft & embed pages.
Working with fields: now you can also change the fields values (and bug-fixed support for Unicode characters)
Saving/exporting PDF: added -decrypt and -flatten option
Grafting & embedding pages: you can graft a page taken from a PDF, and put it over/below another pages. (watermarks, stamps,.. )
8-Jul-2020- Version 1.6 - field get&set, new export options, graft & embed pages.
Password protected files
added commands for adding/changing passwords on a PDF. See methods [pdfHandleupwd] and [pdfHandleopwd]
Forms and Fields
added commands for changing field attributes. See method [pdfHandlefieldattrib]
added commands for flattening single fields. See method [pdfHandleflattenfield]
Annotations
added methods for listing, adding, changing, removing annotations. Currently only a limited set of annotation types are supported: highlight, underline, strikeout, squiggly. See methods [pageHandleannots] and [pageHandleannot ...]
Page and text structure
added methods for extracting the image/text "blocks" and the bounding box of each text line. These method are the basic building blocks - along with the new Annotation methods - for building an interactive PDF editor. See methods [pageHandleblocks] and [pageHandlelines]
Download
Starting from version 1.2.1, you can download tclMuPdf in a pre-built package with multi-platform support or, if you only need support for a single platform, you can download a lighter package.
Note that a specific platform support (e.g. "Linux 32") is not referred to the hosting O.S. architecture, but it's referred to the architecture of the TclTk interpreter. E.g. if you have a 32-bit TclTk interpreter running on a 64-bit Linux, you need the tclMuPdf package for linux-x32.
Version 1.6 (July 2020)
[L1 ] FULL (Win 32/64, Linux 32/64, MacOS) (Warning: 33MB)
Package mupdf integrates the MuPDF framework in Tcl. The focus of MuPDF is on speed, small code size, and high-quality anti-aliased rendering. The main goal of this integration is to generate images of the pdf pages, in a .png format, or directly in a Tk's photo image type. Thanks to its speed mupdf can be used for building interactive pdf-viewers with high-quality and real-time zooming. mupdf is a binary package, distributed in a multi-platform bundle, i.e. it can be used on
Windows 32/64 bit
Linux 32/64 bit
MacOS 64 bit
Just an example to get the flavor of how to use mupdf:
# open a file and save 1st page as a .png file
package require mupdf
set pdf [mupdf::open /mydir/sample.pdf]
set page [$pdf getpage 0] ;# 0 is the 1st page
$page savePNG /mydir/page0.png
$pdf quit
MuPDF with and without Tk
Starting from version 1.1, you can also run mupdf from a tclsh interpreter, without loading Tk. The following command
package require mupdf-notk
can be used in a tclsh interpreter to load the package without requiring Tk support. You will be still able to save images as PNG files, but of course some subcommands related to Tk won't be available (e.g saveImage ) The command
package require mupdf
loads the full package (and requires Tk).
mupdf Commands
mupdf supports the following commands:
mupdf::openfilename ?-passwordpassword?
This is the main command: it opens the PDF-file filename and returns a pdfHandle to be used in subsequent operations. If filename is password-protected, you may specify a password adding the option -password; if option -password is not specified, mupdf will ask for a password. Read more about it in the section Working with Password Protected Files.
pdfHandleupwduser-password
pdfHandleopwdowner-password
add or change respectively the user-password or the owner-password. In order to reset the passwords,set them to "". Read more about it in the section Working with Password Protected Files.
pdfHandlequit
close and destroy the pdfHandle without saving the changes. All the related resources (e.g. opened pages) will be closed.
pdfHandleclose ?-flattenbool? ?-decryptbool?
close and destroy the pdfHandle and save the changes. All the related resources (e.g. opened pages) will be closed. See export for the meaning of the various options.
pdfHandlefullname
return the fully normalized pathname of the pdf-file.
pdfHandleauthentication
return the current authentication mode for pdfHandle. It may be none (no auth required), user (opened with user's password), owner (opened with owner's password).
pdfHandleversion
return the document's internal PDF-version.
pdfHandlenpages
return the number of pages.
pdfHandlegetpagen
return a pageHandle to be used in subsequent operations. Note that first page is page 0. Note that if the requested page is currently opened, getpage reuses the handle of the opened page.
pdfHandleanchoranchorName
return the location of anchorName as list of 3 numbers:
a page number ( -1 if anchorName is not found )
x displacement
y displacement x and y are hints for locating the anchor: they represent the displacement from the upper-left corner of the page (0,0).
pdfHandleopenedpages
return the list of all pageHandles currently opened related to pdfHandle
pdfHandlecloseallpages
close all currently opened pages related to pdfHandle
pdfHandlefields
return a list of field-records. Each field-record is a list of three elements:
the field-name
the field-type (button, radiobutton, checkbox, text, combobox, listbox, signature or unknown)
the field-value Note that for a signature field, if a signature is present the returned field-value is simply the fixed string <<signature>>.
pdfHandlefieldfieldname
return the field's value, or raise an error if fieldname is not a valid field. Warning: field-names with accented characters or in general characters from latin alphabets are accepted (even not encorauged). Fields-names with characters from non-latin alphabets (greek, russian, chinese, ...) are not supported.
pdfHandlefieldfieldnamevalue
set the field's value, or raise an error if fieldname is not a valid field. Warning: see limitations in Notes and limitations about field names and values for details.
pdfHandlefieldattribfieldname
get all the field's attributes, as a list of options/values, or raise an error if fieldname is not a valid field. Currently supported options are:
-readonly
pdfHandlefieldattribfieldname ?options?
set the field's attributes, or raise an error if fieldname is not a valid field. Currently supported options are:
-readonlybool
pdfHandleflattenfieldfieldname ?...?
flatten all the listed fields appearances (and removes all the listed fields from the field-table). Note that flattening N fields with a single command is far more efficient than running N flattening commands; this is especially true for documents with many pages.
pdfHandlesignatures
return a list of signature field-records . Each field-record is a list of two elements:
the field-name
the field-value Empty signature fields (blanc signatures) have a field-value equal to "" (empty string). Currently, filled signature fields are simply denoted with the fixed string <<signature>>.
pdfHandlehaschanges
return 1 if pdfHandle has been changed, otherwise 0.
pdfHandlecanbesavedincrementally
return 1 if pdfHandle can be saved in incremental-mode, otherwise 0.
save the current document and its changes in an alternative filename. Valid options are:
-flattenbool - (**DEPRECATED**) flat all form's fields and annotations (default is false)
-decryptbool - ((**DEPRECATED**) if bool is true remove the password protection from an encrypted pdf. If bool is false keep the original password protection. Note that the target filename should be different from the original pdf-file related with pdfHandle and in general, different from the name of any pdf-file currently opened in this process. When a pdfHandle is closed (see mupdf::close or "pdfHandleclose"), all the changes will be saved to its original pdf-file. (see also mupdf::quit or "pdfHandlequit" for closing without saving changes). Saving with the -flatten option, is now (**DEPRECATED**). You should use "pdfHandleflattenfieldfieldname1 ..." and then save/export the document. Saving with the -decrypt option is now (**DEPRECATED**). The default is to remove the password protection, unless the opwd or upwd commands explicitely set new passwords.
extract the i-th embedded file. ( i >= 0 ) If option -dir is not specified, the embedded file is saved in the current directory. If option -as is not specified, embedded file is saved with its original name
search the string needle starting from page-number pagenum (default is page 0) and returning up to hits results (default is 10). The result of search subcommand is a list of page-positions. Each page-positions is a list of two elements:
the page-number
a list with the 4 coords of the box enclosing the searched needle Next results can be retrived with the search..more subcommand.
pdfHandlesearch..more ?-maxhits?
return a list of the next hits elements matching the last given needle. The result of search..more subcommand is a list of page-positions similar to the list returned by search.
pdfHandlegraftpageHandle
import in the currently open document referred by pdfHandle the full content of the page referred by pageHandle. The page contents are just imported, not displayed, and should be controlled via the next embed command. The result of graft is a graftID that should be used by the next embed ... command for displaying the image of the source page within one or more pages of the document. Note: this page-image is not a raster-image; it's vector based and hence remains accurate across zooming levels. Note: graftID is unique for each opened document pdfHandle and it's valid until pdfHandle is closed.
pageHandleembedgraftID ?...options...?
put a copy of a grafted page in the page referred by pageHandle. pageHandle should be a page of the same opened document who returned that graftID. Valid options are:
-overbool - displays the contents of the grafted page over (or below) the contents of the current page (default is true).
-angletheta - rotate the grafted imaged by theta degrees (-360.0 ..+360.0), Default is 0.0.
-zoomfactor - enlarge/shrink the grafted imaged by a factor of factor (default is 1.0).
-fromx0y0 ?x1y1? - just copy a rectangular sub-region of the grafted image. (x0,y0) and (x1,y1) specify diagonally opposite corners of the rectangle; (0,0) is the upper-left corner of the (visible portion of the) grafted page. If x1 and y1 are not specified, the default value is the bottom-right corner of the grafted page.
-tox0y0 ?x1y1? - place the grafted page in a rectangular subregion of the destination page. If x0 and y0 are not specifified, the grafted page is placed at (0,0) i.e. at the upper-left corner of the destination page. If x1 and y1 are not specified, the default value is the bottom-right corner of the destination page.
pageHandleannots
return the list of annotations-ID on pageHandle.
pageHandleannotannotID
return the list of the (so far recognized) annotIDs attributes. Two special read-only attributes -type and -rect' are provided for each annotation.
pageHandleannotannotIDattribute
get the value of attribute for the annotation annotID.
set the the value of one or more attributes of the annotation annotID.
pageHandleannotannotIDdelete
delete the annotation annotID
pageHandleannotcreatetype ?attributevalue ...?
create a new annotation. Currently supported types are: highlight, underline, strikeout, squiggly. Common attributes for each supported type are:
-color { R G B } - R,G,B must be decimal numers between 0.0 and 1.0 Specific options for highlight, underline, strikeout, squiggly are:
-vertices {x0y0x1y1 ... } - a list of 4x integers denoting the bounding boxes of the text to be marked. Note: these coordinates are not necessarily related to the text on a page. A new annotationID is returned.
pageHandleblocks
return the list of image/text blocks in pageHandle. A block is a list of 5 elements with the following format: textblock|imageblockx0y0x1y1
pageHandleclose
close and free all the resources of the page referred by pageHandle. the handle pdfHandle is destroyed.
pageHandlesize
return the physical size of the page as a list of two decimal numbers. Note that page size is expressed in points, i.e. 1/72 inch.
pageHandledocref
return a reference to the related pdf-document as a pdfHandle
pageHandlelines
return the list of the bbox of the text lines in pageHandle. A bbox is a list of 4 elements with the following format: x0y0x1y1
render the page in a .png file named filename. With a default -zoom factor equal to 1.0, a page whose size is W x H points is rendered as a raster image of W x H pixels. If -zoom is specified, the resulting image size is scaled by a factor of zoom. By default the whole page is rendered; the -from option, allows you to render only a given rectangular area of the page. x0y0 are the coords of the top-left corner and x1y1 are for the bottom-right corner. These coords must be expressed in terms of the physical size of the page, i.e in points Note that if these coords lies outside of the page, only the intersection of this area with the page area is rendered.
...
set page [$pdf getpage 0] ;# 0 is the 1st page
lassign [$page size] dx dy
# save just the upper half of the page
$page savePNG /mydir/page0.png -zoom 2.25 -from 0 0 $dx [expr $dy/2]
...
render the page in an existing Tk's photo image. The width and/or height of image are unchanged if the user has set on it an explicit image width or height (with the -width and/or -height configuration options, respectively). About the -zoom and -from options, the same rules for the savePNG apply. Option -to allows you to place the resulting raster image at the x0y0 coords of the destination image. By default, is -to0.00.0 NOTE: this command is not available with the package mupdf-notk.
pageHandleaddsigfieldfieldnamex0y0x1y1
add a blank signature field in a rectangular box at coords x0y0x1y1. fieldname must be unique among the existing field names.
search the string needle in the current page and return up to hitspositions (default is 10). By default search starts from top of the page. If you need to find the next hits, use option -fromtopfalse. The result of search subcommand is a list of positions. Each positions is a list with the 4 coords of the box enclosing the searched needle.
pageHandleimageslist ?-idimageID?
return a list of all the images contained in the page referred by pageHandle. The result of imageslist subcommand is a list of image-records. Each image-record is a list of six elements:
image's bit per component (number of color components may be inferred from colorspace)
mask-flag : 1 means that the image has a pixel-mask (i.e. some transparent pixels) If option -id is present, the resulting list is limited to the image-record for imageID.
if option -id is specified, extract and save the image referred by imageID (see imageslist). If option -id is missing, all the images contained in a page are extracted and saved. If option -dir is not specified, images are saved in the current directory. If option -as is not specified, images are saved with a name derived from the default mupdf::imagenamesformat (see below), otherwise images are saved as pattern (for pattern rules see below for mupdf::imagenamesformat). if option -transparency is true, save the (semi)transparent pixels (if any), otherwise transparent pixels (if any) are rendered as white pixels. extract returns a list of extracted-records. Each extracted-record is a list of three elements:
image-ID (unique for each page)
image-name (pdf page's internal name)
saved filename (empty string if the image was skipped (unknow format...))
mupdf::imagenamesformat ?pattern?
a pattern is a parametric filename specification similar to the format specification used by the C printf function. If pattern is not specified, return the currently defined default pattern. If pattern is specified, set the default pattern. When the "pageHandleimagesextract ..." command is called, all the images are saved with a filename based on a pattern (This pattern can be explicit, if option -as is present, or it can be implicit, based on the default mupdf::imagenamesformat). a pattern is a a simple filename specification (just the base-name, since the extension of the extracted images (png, jpg, ...) is automatically determined.) with zero or more special symbols like the following ones:
%p : page number (first page is 1)
%P : total number of pages
%i : image number - images in a page are numbered starting from 1
%I : total number of images (in the current page) Special symbols may also be written with a padding-specification like %5P; this notation means the the symbol %P should be padded as a 5-character string with leading '0's. If more than one image is extracted in a single operation, and pattern does not contain the %i symbol (the image number), then -%i is implicitely appended in order to avoid a filename collision. Assuming that the current page is the page 123 (i.e the 124th page), the following command
$pageHandle images extract -as "IMG_%5p"
will generate IMG_00124-1.jpg, IMG_00124-2.jpg ..... (note: the file extension may be different)
$pageHandle images extract -as "Z%5p(%2i)"
will generate Z00124(01).jpg, Z00124(02).jpg ..... (note: the file extension may be different)
mupdf::closehandle (**DEPRECATED**)
This command has been deprecated since mupdf 1.5. Use "pdfHandleclose...." or "pageHandleclose". if handle refers to a pageHandle, close the page. if handle refers to a pdfHandle, close the pdf (updating its original pdf-file) and all its opened pages.
mupdf::quitpdfHandle (**DEPRECATED**)
close and destroy the pdfHandle without saving the changes. This command has been deprecated since mupdf 1.5 . Use "pdfHandlequit" .
mupdf::isobjecthandle
return 1 if handle is a valid reference to a pdf or a page.
mupdf::typehandle
return document or page if handle is a valid reference, else raise an error.
mupdf::documents
return a list of the currently opened pdfHandles
mupdf::documentnames
return a list of pdf-filenames currently opened (fully normalized filenames).
mupdf::isopenfilename
check if filename is among the currently opened pdf-files.
mupdf::cli_passwordhelper ?helperProc?
get/set the helper procedure for shell-like applications. If helperProc is ', then the default helper is re-set. See section Working with Password Protected Files'.
mupdf::tk_passwordhelper ?helperProc?
get/set the helper procedure for applications with a Tk graphical interface. If helperProc is ', then the default helper is re-set. See section Working with Password Protected Files'.
mupdf::libinfo
return specific attributes of the underlying MuPdf libray as a list of keywords and their values. The provided keywords are:
version
The version of the underlying MuPDf library
..more to come ..
Working with Password Protected Files
You can open a password-protected PDF in a non-interactive or in an interactive way. With the first way, non-interactive way, you must provide in advance a password
set pdf [mupdf::open book.pdf -password "123open"]
If password is wrong then an error is raised; look at the error message and check for the errorcode: it should be MUPDF WRONGPASSWORD. Note that there's no distinction between owner's password and user's password; if you provide the right owner's password, the PDF is opened in owner-mode, if you provide the right user's password, the PDF is opened in user-mode. You can check if PDF has been opened in user-mode or owner-mode by calling the authentication command.
set pdf [mupdf::open book.pdf -password "123open"]
# if we are here, it means that password was OK
set mode [$pdf authentication]
# "none" means that book.pdf was not password-protected
# "user" means that the supplyed password was the user's password
# "owner" means ...
The second way , interactive way, does not require to provide an explicit password; if the PDF is password-protected, mupdf will ask for a password. Depending on the nature of your application (with or without Tk), mupdf will select and call a predefined (yet customizable) helper procedure. These predefined, built-in procedures can be changed with the mupdf::cli_passwordhelper or mupdf::tk_passwordhelper command.
# template for a (shell-like) password-helper procedure
proc mypswdhelper {filename} {
... ask for a password ....
.... get the password ....
....
return $password
}
mupdf::cli_passwordhelper mypswdhelper
# template for a (GUI) password-helper procedure
proc myGUIpswdhelper {filename} {
... raise some popup ...
... ask for a password ....
.... get the password ...
.... close the popup
return $password
}
mupdf::tk_passwordhelper myGUIpswdhelper
Removing protection from a password protected files
If you open a password-protected file and export it, by default the resulting PDF is saved without password. You can explicitely control this behaviour by appending the -decrypt option to the export or close commands (default is -decrypttrue).
Adding or changing a password
After opening a PDF, you can add or change the user/owner password with the opwd or the upwdcommands,like in the following example
set pdf [mupdf::open mybook.pdf]
# if mybook.pdf is proteccted, insert the password
$pdf upwd "my user-password"
$pdf opwd "my owner-password"
$pdf close ;# ..or $pdf export ...
Notes and limitations about field names and values
Due to current limitations of the underlying MuPdf library, field names and values should be limited to latin alphabets only. See the note enclosed with MuPdf's BUG 696478 (Nov 2018): '' ... "There is, however, a limitation with our form filling support that still
needs to be addressed: it only supports PDFDocEncoding, not Unicode.
... "We can currently fill out the form fields in any language, but the display code still only handles the Latin alphabet." '' This means that you can enter text in a form field in any alphabet (tested with Russian, Chinese, Greek, ...) but the rendered text for the non-latin alphabets will appear wrong. Another major limitation is the rendering of fields other that 'text' widgets, i.e. checkbox, radiobuttons... For these kind of widgets the support of the underlying library is still incomplete, in particular for values expressed in non-ASCII characters (e.g. accented letters ... )
LImitations
Full support for portfolio management is still incomplete; commands for adding/removing/reordering embedded files will require a more robust mupdf-core implementation.