From a7c3d73078f9e0cfc12d7eee86d0e2de197768ab Mon Sep 17 00:00:00 2001 From: Tor Andersson Date: Mon, 25 Apr 2016 15:43:26 +0200 Subject: Add 'mutool run' documentation. --- docs/mutool/examples/create-thumbnail.js | 19 + docs/mutool/examples/draw-device.js | 45 ++ docs/mutool/examples/draw-document.js | 9 + docs/mutool/examples/pdf-create-lowlevel.js | 63 +++ docs/mutool/examples/pdf-create.js | 35 ++ docs/mutool/examples/pdf-merge.js | 66 +++ docs/mutool/examples/trace-device.js | 102 +++++ docs/mutool/run.html | 635 ++++++++++++++++++++++++++++ 8 files changed, 974 insertions(+) create mode 100644 docs/mutool/examples/create-thumbnail.js create mode 100644 docs/mutool/examples/draw-device.js create mode 100644 docs/mutool/examples/draw-document.js create mode 100644 docs/mutool/examples/pdf-create-lowlevel.js create mode 100644 docs/mutool/examples/pdf-create.js create mode 100644 docs/mutool/examples/pdf-merge.js create mode 100644 docs/mutool/examples/trace-device.js create mode 100644 docs/mutool/run.html (limited to 'docs/mutool') diff --git a/docs/mutool/examples/create-thumbnail.js b/docs/mutool/examples/create-thumbnail.js new file mode 100644 index 00000000..cf7a5886 --- /dev/null +++ b/docs/mutool/examples/create-thumbnail.js @@ -0,0 +1,19 @@ +// Create a PDF containing thumbnails of pages rendered from another PDF. + +var pdf = new PDFDocument() + +var subdoc = new Document("pdfref17.pdf") + +var resources = { XObject: {} } + +var contents = new Buffer() +for (var i=0; i < 5; ++i) { + var pixmap = subdoc.loadPage(1140+i).toPixmap([0.2,0,0,0.2,0,0], DeviceRGB) + resources.XObject["Im" + i] = pdf.addImage(new Image(pixmap)) + contents.writeLine("q 100 0 0 150 " + (50+100*i) + " 50 cm /Im" + i + " Do Q") +} + +var page = pdf.addPage([0,0,100+i*100,250], 0, resources, contents) +pdf.insertPage(-1, page) + +pdf.save("out.pdf") diff --git a/docs/mutool/examples/draw-device.js b/docs/mutool/examples/draw-device.js new file mode 100644 index 00000000..4912e956 --- /dev/null +++ b/docs/mutool/examples/draw-device.js @@ -0,0 +1,45 @@ +// Use device interface to draw some graphics and save as a PNG. + +var font = new Font("Times-Roman"); +var image = new Image("example.png"); +var path, text; + +var pixmap = new Pixmap(DeviceRGB, [0,0,500,600]); +pixmap.clear(255); +var device = new DrawDevice(pixmap); +var transform = [2,0,0,2,0,0] +{ + text = new Text(); + { + text.showString(font, [16,0,0,-16,100,30], "Hello, world!"); + text.showString(font, [0,16,16,0,15,100], "Hello, world!"); + } + device.fillText(text, transform, DeviceGray, [0], 1); + + path = new Path(); + { + path.moveTo(10, 10); + path.lineTo(90, 10); + path.lineTo(90, 90); + path.lineTo(10, 90); + path.closePath(); + } + device.fillPath(path, false, transform, DeviceRGB, [1,0,0], 1); + device.strokePath(path, {dashes:[5,10], lineWidth:3, lineCap:'Round'}, transform, DeviceRGB, [0,0,0], 1); + + path = new Path(); + { + path.moveTo(100,100); + path.curveTo(150,100, 200,150, 200,200); + path.curveTo(200,300, 0,300, 100,100); + path.closePath(); + } + device.clipPath(path, true, transform); + { + device.fillImage(image, Concat(transform, [300,0,0,300,0,0]), 1); + } + device.popClip(); +} +//device.flush(); + +pixmap.saveAsPNG("out.png"); diff --git a/docs/mutool/examples/draw-document.js b/docs/mutool/examples/draw-document.js new file mode 100644 index 00000000..1e285ede --- /dev/null +++ b/docs/mutool/examples/draw-document.js @@ -0,0 +1,9 @@ +// Draw all pages in a document and save them as PNG files. + +var doc = new Document(argv[1]); +var n = doc.countPages(); +for (var i = 0; i < n; ++i) { + var page = doc.loadPage(i); + var pixmap = page.toPixmap(Identity, DeviceRGB); + pixmap.saveAsPNG("out" + (i+1) + ".png"); +} diff --git a/docs/mutool/examples/pdf-create-lowlevel.js b/docs/mutool/examples/pdf-create-lowlevel.js new file mode 100644 index 00000000..b55e22cf --- /dev/null +++ b/docs/mutool/examples/pdf-create-lowlevel.js @@ -0,0 +1,63 @@ +// Create a PDF from scratch. + +// This example creates a new PDF file from scratch, using only the low level APIs. +// This assumes a basic working knowledge of the PDF file format. + +// Create a new empty document with no pages. +var pdf = new PDFDocument() + +// Create and add a font resource. +var font = pdf.addObject({ + Type: "Font", + Subtype: "Type1", + Encoding: "WinAnsiEncoding", + BaseFont: "Times-Roman", +}) + +// Create and add an image resource: +// Allocate a slot for a new object and get a reference to it. +var image = pdf.createObject() +// Write a dictionary object into the slot. +image.writeObject({ + Type: "XObject", + Subtype: "Image", + Width: 4, + Height: 2, + BitsPerComponent: 8, + ColorSpace: "DeviceGray", + // The compression filter to be used: + Filter: "ASCIIHexDecode", +}) +// Write raw stream data into the slot; hex encoded +// to match the Filter entry in the dictionary. +image.writeRawStream("004488CCEEBB7733>") + +// Create resource dictionary. +var resources = pdf.addObject({ + Font: { Tm: font }, + XObject: { Im0: image }, +}) + +// Create content stream. +var buffer = new Buffer() +buffer.writeLine("10 10 280 330 re s") +buffer.writeLine("q 200 0 0 200 50 100 cm /Im0 Do Q") +buffer.writeLine("BT /Tm 16 Tf 50 50 TD (Hello, world!) Tj ET") +var contents = pdf.addStream(buffer) + +// Create page object. +var page = pdf.addObject({ + Type: "Page", + MediaBox: [0,0,300,350], + Contents: contents, + Resources: resources, +}) + +// Insert page object into page tree. +var pagetree = pdf.getTrailer().Root.Pages +pagetree.Count = 1 +pagetree.Kids = [ page ] +page.Parent = pagetree + +// Save the document. +pdf.save("out.pdf") diff --git a/docs/mutool/examples/pdf-create.js b/docs/mutool/examples/pdf-create.js new file mode 100644 index 00000000..38c193a3 --- /dev/null +++ b/docs/mutool/examples/pdf-create.js @@ -0,0 +1,35 @@ +// Create a PDF from scratch using helper functions. + +// This example creates a new PDF file from scratch, using helper +// functions to create resources and page objects. +// This assumes a basic working knowledge of the PDF file format. + +// Create a new empty document with no pages. +var pdf = new PDFDocument() + +// Load built-in font and create WinAnsi encoded simple font resource. +var font = pdf.addSimpleFont(new Font("Times-Roman")) + +// Load PNG file and create image resource. +var image = pdf.addImage(new Image("example.png")) + +// Create resource dictionary. +var resources = pdf.addObject({ + Font: { Tm: font }, + XObject: { Im0: image }, +}) + +// Create content stream data. +var contents = + "10 10 280 330 re s\n" + + "q 200 0 0 200 50 100 cm /Im0 Do Q\n" + + "BT /Tm 16 Tf 50 50 TD (Hello, world!) Tj ET\n" + +// Create a new page object. +var page = pdf.addPage([0,0,300,350], 0, resources, contents) + +// Insert page object at the end of the document. +pdf.insertPage(-1, page) + +// Save the document to file. +pdf.save("out.pdf") diff --git a/docs/mutool/examples/pdf-merge.js b/docs/mutool/examples/pdf-merge.js new file mode 100644 index 00000000..a468738a --- /dev/null +++ b/docs/mutool/examples/pdf-merge.js @@ -0,0 +1,66 @@ +// A re-implementation of "mutool merge" in JavaScript. + +function graftObject(dstDoc, srcDoc, srcObj, map) { + var srcNum, dstRef, dstObj + if (!map) + map = [] + if (srcObj.isIndirect()) { + srcNum = srcObj.toIndirect() + if (map[srcNum]) + return map[srcNum] + map[srcNum] = dstRef = dstDoc.createObject() + dstRef.writeObject(graftObject(dstDoc, srcDoc, srcObj.resolve(), map)) + if (srcObj.isStream()) + dstRef.writeRawStream(srcObj.readRawStream()) + return dstRef + } + if (srcObj.isArray()) { + dstObj = dstDoc.newArray() + srcObj.forEach(function (key, val) { + dstObj[key] = graftObject(dstDoc, srcDoc, val, map) + }) + return dstObj + } + if (srcObj.isDictionary()) { + dstObj = dstDoc.newDictionary() + srcObj.forEach(function (key, val) { + dstObj[key] = graftObject(dstDoc, srcDoc, val, map) + }) + return dstObj + } + return srcObj /* primitive objects are not bound to a document */ +} + +function copyPage(dstDoc, srcDoc, pageNumber, map) { + var srcPage, dstPage + srcPage = srcDoc.findPage(pageNumber) + dstPage = dstDoc.newDictionary() + if (srcPage.MediaBox) dstPage.MediaBox = graftObject(dstDoc, srcDoc, srcPage.MediaBox, map) + if (srcPage.Rotate) dstPage.Rotate = graftObject(dstDoc, srcDoc, srcPage.Rotate, map) + if (srcPage.Resources) dstPage.Resources = graftObject(dstDoc, srcDoc, srcPage.Resources, map) + if (srcPage.Contents) dstPage.Contents = graftObject(dstDoc, srcDoc, srcPage.Contents, map) + dstDoc.insertPage(-1, dstDoc.addObject(dstPage)) +} + +function copyAllPages(dstDoc, srcDoc) { + var k, n = srcDoc.countPages() + var srcMap = [] + for (k = 0; k < n; ++k) + copyPage(dstDoc, srcDoc, k, srcMap) +} + +function pdfmerge() { + var srcDoc, dstDoc, i + + dstDoc = new PDFDocument() + for (i = 2; i < argv.length; ++i) { + srcDoc = new PDFDocument(argv[i]) + copyAllPages(dstDoc, srcDoc) + } + dstDoc.save(argv[1]) +} + +if (argv.length < 3) + print("usage: mutool run pdf-merge.js output.pdf input1.pdf input2.pdf ...") +else + pdfmerge() diff --git a/docs/mutool/examples/trace-device.js b/docs/mutool/examples/trace-device.js new file mode 100644 index 00000000..9d7d4373 --- /dev/null +++ b/docs/mutool/examples/trace-device.js @@ -0,0 +1,102 @@ +var Q = JSON.stringify + +var pathPrinter = { + moveTo: function (x,y) { print("moveTo", x, y) }, + lineTo: function (x,y) { print("lineTo", x, y) }, + curveTo: function (x1,y1,x2,y2,x3,y3) { print("curveTo", x1, y1, x2, y2, x3 ,y3) }, + closePath: function () { print("closePath") }, +} + +var textPrinter = { + showGlyph: function (f,m,g,u,v,b) { print("glyph",f,m,g,u,v,b) }, +} + +var traceDevice = { + fillPath: function (path, evenOdd, ctm, colorSpace, color, alpha) { + print("fillPath", evenOdd, ctm, colorSpace, color, alpha) + path.walk(pathPrinter) + }, + clipPath: function (path, evenOdd, ctm) { + print("clipPath", evenOdd, ctm) + path.walk(pathPrinter) + }, + strokePath: function (path, stroke, ctm, colorSpace, color, alpha) { + print("strokePath", Q(stroke), ctm, colorSpace, color, alpha) + path.walk(pathPrinter) + }, + clipStrokePath: function (path, stroke, ctm) { + print("clipStrokePath", Q(stroke), ctm) + path.walk(pathPrinter) + }, + + fillText: function (text, ctm, colorSpace, color, alpha) { + print("fillText", ctm, colorSpace, color, alpha) + text.walk(textPrinter) + }, + clipText: function (text, ctm) { + print("clipText", ctm) + text.walk(textPrinter) + }, + strokeText: function (text, stroke, ctm, colorSpace, color, alpha) { + print("strokeText", Q(stroke), ctm, colorSpace, color, alpha) + text.walk(textPrinter) + }, + clipStrokeText: function (text, stroke, ctm) { + print("clipStrokeText", Q(stroke), ctm) + text.walk(textPrinter) + }, + ignoreText: function (text, ctm) { + print("ignoreText", ctm) + text.walk(textPrinter) + }, + + fillShade: function (shade, ctm, alpha) { + print("fillShade", shade, ctm, alpha) + }, + fillImage: function (image, ctm, alpha) { + print("fillImage", image, ctm, alpha) + }, + fillImageMask: function (image, ctm, colorSpace, color, alpha) { + print("fillImageMask", image, ctm, colorSpace, color, alpha) + }, + clipImageMask: function (image, ctm) { + print("clipImageMask", image, ctm) + }, + + beginMask: function (area, luminosity, colorspace, color) { + print("beginMask", area, luminosity, colorspace, color) + }, + endMask: function () { + print("endMask") + }, + + popClip: function () { + print("popClip") + }, + + beginGroup: function (area, isolated, knockout, blendmode, alpha) { + print("beginGroup", area, isolated, knockout, blendmode, alpha) + }, + endGroup: function () { + print("endGroup") + }, + beginTile: function (area, view, xstep, ystep, ctm, id) { + print("beginTile", area, view, xstep, ystep, ctm, id) + return 0 + }, + endTile: function () { + print("endTile") + }, + + close: function () { + print("close") + }, +} + +if (argv.length != 3) + print("usage: mutool run trace-device.js document.pdf pageNumber") +else { + var doc = new Document(argv[1]); + var page = doc.loadPage(parseInt(argv[2])-1); + page.run(traceDevice, Identity); +} diff --git a/docs/mutool/run.html b/docs/mutool/run.html new file mode 100644 index 00000000..07f852de --- /dev/null +++ b/docs/mutool/run.html @@ -0,0 +1,635 @@ + + + +mutool run: reference + + + + +

+MuPDF from JavaScript +

+ +

+The 'mutool run' command executes a JavaScript program, which has access to most of the features of the MuPDF library. +The command supports ECMAScript 5 syntax in strict mode. +All of the MuPDF constructors and functions live in the global object, and the command line arguments are accessible +from the global 'argv' object. + +

+mutool run script.js [ arguments ... ]
+
+ +

+If invoked without any arguments, it will drop you into an interactive REPL (read-eval-print-loop). +On the interactive prompt, if you prefix a line with an equal ('=') character it will automatically print the result +of the line. + +

+Example scripts +

+ +

+Create and edit PDF documents: + +

+ +

+Graphics and the device interface: + +

+ +

+Advanced examples: + +

+ +

+JavaScript Shell +

+ +

+Several global functions that are common for command line shells are available: + +

+
gc(report) +
Run the garbage collector to free up memory. Optionally report statistics on the garbage collection. +
load(fileName) +
Load and execute script in 'fileName'. +
print(...) +
Print arguments to stdout, separated by spaces and followed by a newline. +
quit() +
Exit the shell. +
read(fileName) +
Read the contents of a file and return them as a UTF-8 decoded string. +
readline() +
Read one line of input from stdin and return it as a string. +
require(module) +
Load a JavaScript module. +
write(...) +
Print arguments to stdout, separated by spaces. +
+ +

+Buffer +

+ +

+The Buffer objects are used for working with binary data. +They can be used much like arrays, but are much more efficient since they +only store bytes. + +

+
new Buffer() +
Create a new empty buffer. +
readFile(fileName) +
Create a new buffer with the contents of a file. +
Buffer#length +
The number of bytes in the buffer. +
Buffer#[n] +
Read/write the byte at index 'n'. Will throw exceptions on out of bounds accesses. +
Buffer#writeByte(b) +
Append a single byte to the end of the buffer. +
Buffer#writeRune(c) +
Encode a unicode character as UTF-8 and append to the end of the buffer. +
Buffer#writeLine(...) +
Append arguments to the end of the buffer, separated by spaces, ending with a newline. +
Buffer#write(...) +
Append arguments to the end of the buffer, separated by spaces. +
Buffer#save(fileName) +
Write the contents of the buffer to a file. +
+ +

+Matrices and Rectangles +

+ +

+Matrices are simply 6-element arrays representing a 3-by-3 transformation matrix as + +

+/ a b 0 \
+| c d 0 |
+\ e f 1 /
+
+ +

+This matrix is represented in JavaScript as [a,b,c,d,e,f]. + +

+
Identity +
The identity matrix, short hand for [1,0,0,1,0,0]. +
Scale(sx, sy) +
Return a scaling matrix, short hand for [sx,0,0,sy,0,0]. +
Translate(tx, ty) +
Return a translation matrix, short hand for [1,0,0,1,tx,ty]. +
Concat(a, b) +
Concatenate matrixes a and b. Bear in mind that matrix multiplication is not commutative. +
+ +

+Rectangles are 4-element arrays, specifying the minimum and maximum corners (typically +upper left and lower right, in a coordinate space with the origin at the top left with +descending y): [ulx,uly,lrx,lry]. + +

+If the minimum x coordinate is bigger than the maximum x coordinate, MuPDF treats the rectangle +as infinite in size. + +

+Document and Page +

+ +

+MuPDF can open many document types (PDF, XPS, CBZ, EPUB, FB2 and a handful of image formats). + +

+
new Document(fileName) +
Open the named document. +
Document#needsPassword() +
Returns true if a password is required to open this password protected PDF. +
Document#authenticatePassword(password) +
Returns true if the password matches. +
Document#getMetaData(key) +
Return various meta data information. The common keys are: "format", "encryption", "info:Author", and "info:Title". +
Document#toPDF() +
Returns a PDFDocument (see below) or null if the document is not a PDF. +
Document#layout(pageWidth, pageHeight, fontSize) +
Layout a reflowable document (EPUB, FB2, or XHTML) to fit the specified page and font size. +
Document#countPages() +
Count the number of pages in the document. This may change if you call the layout function with different parameters. +
Document#loadPage(number) +
Returns a Page object for the given page number. Page number zero (0) is the first page in the document. +
+ +
+
Page#bound() +
Returns a rectangle containing the page dimensions. +
Page#run(device, transform) +
Calls device functions for all the contents on the page, using the specified transform matrix. +The device can be one of the built-in devices or a JavaScript object with methods for the device calls. +
Page#toPixmap(transform, colorspace) +
Render the page into a Pixmap, using the transform and colorspace. +
Page#toDisplayList() +
Record the contents on the page into a DisplayList. +
Page#search(needle) +
Search for 'needle' text on the page, and return an array with rectangles of all matches found. +
+ +

+ColorSpace +

+ +
+
DeviceGray +
The default grayscale colorspace. +
DeviceRGB +
The default RGB colorspace. +
DeviceBGR +
The default RGB colorspace, but with components in reverse order. +
DeviceCMYK +
The default CMYK colorspace. +
ColorSpace#getNumberOfComponents() +
A grayscale colorspace has one component, RGB has 3, CMYK has 4, and DeviceN may have any number of components. +
+ +

+Pixmap +

+ +

+A Pixmap object contains a color raster image (short for pixel map). +The components in a pixel in the pixmap are all byte values, with the transparency as the last component. +A pixmap also has a location (x, y) in addition to its size; so that they can easily be used to represent +tiles of a page. + +

+
new Pixmap(colorspace, bounds) +
Create a new pixmap. The pixel data is not initialized; and will contain garbage. +
Pixmap#clear(value) +
Clear the pixels to the specifed value. Pass 255 for white, or undefined for transparent. +
Pixmap#bound() +
Return the pixmap bounds. +
Pixmap#getWidth() +
Pixmap#getHeight() +
Pixmap#getNumberOfComponents() +
Pixmap#getStride() +
Number of bytes per row. +
Pixmap#getColorSpace() +
Pixmap#getXResolution() +
Pixmap#getYResolution() +
Image resolution in dots per inch. +
Pixmap#getSample(x, y, k) +
Get the value of component k at position x, y (relative to the image origin: 0, 0 is the top left pixel). +
Pixmap#saveAsPNG(fileName, saveAlpha) +
Save the pixmap as a PNG. Only works for Gray and RGB images. +
+ +

+DrawDevice +

+ +

+The DrawDevice can be used to render to a Pixmap; either by running a Page with it or by calling its methods directly. + +

+
new DrawDevice(pixmap) +
Create a device for drawing into a pixmap. The pixmap bounds used should match the transformed page bounds, +or you can adjust them to only draw a part of the page. +
+ +

+DisplayList and DisplayListDevice +

+ +

+A display list records all the device calls for playback later. +If you want to run a page through several devices, or run it multiple times for any other reason, +recording the page to a display list and replaying the display list may be a performance gain +since then you can avoid reinterpreting the page each time. Be aware though, that a display list +will keep all the graphics required in memory, so will increase the amount of memory required. + +

+
new DisplayList() +
Create an empty display list. +
DisplayList#run(device, transform) +
Play back the recorded device calls onto the device. +
DisplayList#toPixmap(transform, colorspace, solid) +
Render display list to a pixmap. If solid is true, it will render to a white background, otherwise transparent. +
+ +
+
new DisplayListDevice(displayList) +
Create a device for recording onto a display list. +
+ +

+Device +

+ +

+All built-in devices have the methods listed below. Any function that accepts a device will also +accept a JavaScript object with the same methods. Any missing methods are simply ignored, so you +only need to create methods for the device calls you care about. + +

+Many of the methods take graphics objects as arguments: Path, Text, Image and Shade. + +

+The stroking state is a dictionary with keys for: +

+
startCap, dashCap, endCap: +
"Butt", "Round", "Square", or "Triangle". +
lineCap: +
Set startCap, dashCap, and endCap all at once. +
lineJoin: +
"Miter", "Round", "Bevel", or "MiterXPS". +
lineWidth: +
Thickness of the line. +
miterLimit: +
Maximum ratio of the miter length to line width, before beveling the join instead. +
dashPhase: +
Starting offset for dash pattern. +
dashes: +
Array of on/off dash lengths. +
+ +

+Colors are specified as arrays with the appropriate number of components for the color space. + +

+The methods that clip graphics must be balanced with a corresponding popClip. + +

+
Device#fillPath(path, evenOdd, transform, colorspace, color, alpha) +
Device#strokePath(path, stroke, transform) +
Device#clipPath(path, evenOdd, transform, colorspace, color, alpha) +
Device#clipStrokePath(path, stroke, transform) +
Fill/stroke/clip a path. +
+ +
+
Device#fillText(text, transform, colorspace, color, alpha) +
Device#strokeText(text, stroke, transform, colorspace, color, alpha) +
Device#clipText(text, transform) +
Device#clipStrokeText(text, stroke, transform) +
Fill/stroke/clip a text object. +
Device#ignoreText(text, transform) +
Invisible text that can be searched but should not be visible, such as for overlaying a scanned OCR image. +
+ +
+
Device#fillShade(shade, transform, alpha) +
Fill a shade (a.k.a. gradient). TODO: this details of gradient fills are not exposed to JavaScript yet. +
Device#fillImage(shade, transform, alpha) +
Draw an image. An image always fills a unit rectangle [0,0,1,1], so must be transformed to be placed and drawn at the appropriate size. +
Device#fillImageMask(shade, transform, colorspace, color, alpha) +
An image mask is an image without color. Fill with the color where the image is opaque. +
Device#clipImageMask(shade, transform) +
Clip graphics using the image to mask the areas to be drawn. +
+ +
+
Device#beginMask(area, luminosity, backdropColorspace, backdropColor) +
Device#endMask() +
Create a soft mask. Any drawing commands between beginMask and endMask are grouped and used as a clip mask. +If luminosity is true, the mask is derived from the luminosity (grayscale value) of the graphics drawn; +otherwise the color is ignored completely and the mask is derived from the alpha of the group. +
+ +
+
Device#popClip() +
Pop the clip mask installed by the last clipping operation. +
+ +
+
Device#beginGroup(area, isolated, knockout, blendmode, alpha) +
Device#endGroup() +
Push/pop a transparency blending group. Blendmode is one of the standard PDF blend modes: "Normal", "Multiply", "Screen", etc. See the PDF reference for details on isolated and knockout. +
+ +
+
Device#beginTile(areaRect, viewRect, xStep, yStep, transform) +
Device#endTile() +
Draw a tiling pattern. Any drawing commands between beginTile and endTile are grouped and then repeated across the whole page. +Apply a clip mask to restrict the pattern to the desired shape. +
+ +

+Path +

+ +

+A Path object represents vector graphics as drawn by a pen. A path can be either stroked or filled, or used as a clip mask. + +

+
new Path() +
Create a new empty path. +
Path#moveTo(x, y) +
Lift and move the pen to the coordinate. +
Path#lineTo(x, y) +
Draw a line to the coordinate. +
Path#curveTo(x1, y1, x2, y2, x3, y3) +
Draw a cubic bezier curve to (x3,y3) using (x1,y1) and (x2,y2) as control points. +
Path#closePath() +
Close the path by drawing a line to the last moveTo. +
Path#rect(x1, y1, x2, y2) +
Shorthand for moveTo, lineTo, lineTo, lineTo, closePath to draw a rectangle. +
Path#walk(pathWalker) +
Call moveTo, lineTo, curveTo and closePath methods on the pathWalker to replay the path. +
+ +

+Text +

+ +

+A Text object contains text. + +

+
new Text() +
Create a new empty text object. +
Text#showGlyph(font, transform, glyph, unicode, wmode) +
Add a glyph to the text object. Transform is the text matrix, specifying font size and glyph location. For example: [size,0,0,-size,x,y]. +Glyph and unicode may be -1 for n-to-m cluster mappings. +For example, the "fi" ligature would be added in two steps: first the glyph for the 'fi' ligature and the unicode value for 'f'; +then glyph -1 and the unicode value for 'i'. +WMode is 0 for horizontal writing, and 1 for vertical writing. +
Text#showString(font, transform, string) +
Add a simple string to the text object. Will do font substitution if the font does not have all the unicode characters required. +
Text#walk(textWalker) +
Call showGlyph on textWalker for each glyph in the text object. +
+ +

+Font +

+ +

+Font objects can be created from TrueType, OpenType, Type1 or CFF fonts. +In PDF there are also special Type3 fonts. + +

+
new Font(fontName or fileName) +
Create a new font, either using a built-in font name or a filename. +The built-in fonts are: Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic, +Helvetica, Helvetica-Oblique, Helvetica-Bold, Helvetica-BoldOblique, +Courier, Courier-Oblique, Courier-Bold, Courier-BoldOblique, +Symbol, and ZapfDingbats. +
Font#getName() +
Get the font name. +
Font#encodeCharacter(unicode) +
Get the glyph index for a unicode character. Glyph zero (.notdef) is returned if the font does not have a glyph for the character. +
Font#advanceGlyph(glyph, wmode) +
Return advance width for a glyph in either horizontal or vertical writing mode. +
+ +

+Image +

+ +

+Image objects are similar to Pixmaps, but can contain compressed data. + +

+
new Image(pixmap or fileName) +
Create a new image from a pixmap data, or load an image from a file. +
Image#getWidth() +
Image#getHeight() +
Image size in pixels. +
Image#getXResolution() +
Image#getYResolution() +
Image resolution in dots per inch. +
Image#getColorSpace() +
Image#toPixmap(scaledWidth, scaledHeight) +
Create a pixmap from the image. The scaledWidth and scaledHeight arguments are optional, +but may be used to decode a down-scaled pixmap. +
+ +

+PDFDocument and PDFObject +

+ +

+With MuPDF it is also possible to create, edit and manipulate PDF documents +using low level access to the objects and streams contained in a PDF file. + +

+
new PDFDocument() +
Create a new empty PDF document. +
new PDFDocument(fileName) +
Load a PDF document from file. +
Document#toPDF() +
Get access to the raw PDFDocument from a Document; returns null if the document is not a PDF. +
PDFDocument#toDocument() +
Cast the PDF document to a Document. +
PDFDocument#save(fileName) +
Write the PDF document to file. +
+ +

+PDF Object Access +

+ +

+A PDF document contains objects, similar to those in JavaScript: arrays, dictionaries, strings, booleans, and numbers. +At the root of the PDF document is the trailer object; which contains pointers to the meta data dictionary and the +catalog object which contains the pages and other information. + +

+Pointers in PDF are also called indirect references, +and are of the form "32 0 R" (where 32 is the object number, 0 is the generation, and R is magic syntax). +All functions in MuPDF dereference indirect references automatically. + +

+PDF has two types of strings: /Names and (Strings). All dictionary keys are names. + +

+Some dictionaries in PDF also have attached binary data. These are called streams, and may be compressed. + +

+
PDFDocument#getTrailer() +
The trailer dictionary. This contains indirect references to the Root and Info dictionaries. +
PDFDocument#countObjects() +
Return the number of objects in the PDF. Object number 0 is reserved, and may not be used for anything. +
PDFDocument#createObject() +
Allocate a new numbered object in the PDF, and return an indirect reference to it. +The object itself is uninitialized. +
+ +

+PDFObjects are always bound to the document that created them. +Do NOT mix and match objects from one document with another document! + +

+
PDFDocument#addObject(obj) +
Add 'obj' to the PDF as a numbered object, and return an indirect reference to it. +
PDFDocument#addStream(buffer) +
Create a stream object with the contents of 'buffer', add it to the PDF, and return an indirect reference to it. +
PDFDocument#newNull() +
PDFDocument#newBoolean(boolean) +
PDFDocument#newInteger(number) +
PDFDocument#newReal(number) +
PDFDocument#newString(string) +
PDFDocument#newName(string) +
PDFDocument#newIndirect(objectNumber, generation) +
PDFDocument#newArray() +
PDFDocument#newDictionary() +
+ +

+All functions that take PDF objects, do automatic translation between JavaScript objects +and PDF objects using a few basic rules. Null, booleans, and numbers are translated directly. +JavaScript strings are translated to PDF names, unless they are surrounded by parentheses: +"Foo" becomes the PDF name /Foo and "(Foo)" becomes the PDF string (Foo). + +

+Arrays and dictionaries are recursively translated to PDF arrays and dictionaries. +Be aware of cycles though! The translation does NOT cope with cyclic references! + +

+The translation goes both ways: PDF dictionaries and arrays can be accessed similarly +to JavaScript objects and arrays by getting and setting their properties. + +

+
PDFObject#get(key or index) +
PDFObject#put(key or index, value) +
PDFObject#delete(key or index) +
Access dictionaries and arrays. Dictionaries and arrays can also be accessed using normal property syntax: obj.Foo = 42; delete obj.Foo; x = obj[5]. +
PDFObject#resolve() +
If the object is an indirect reference, return the object it points to; otherwise return the object itself. +
PDFObject#isArray() +
PDFObject#isDictionary() +
PDFObject#forEach(function(key,value){...}) +
Iterate over all the entries in a dictionary or array and call fun for each key-value pair. +
+ +

+The only way to access a stream is via an indirect object, since all streams +are numbered objects. + +

+
PDFObject#isIndirect() +
Is the object an indirect reference. +
PDFObject#toIndirect() +
Return the object number the indirect reference points to. +
PDFObject#isStream() +
True if the object is an indirect reference pointing to a stream. +
PDFObject#readStream() +
Read the contents of the stream object into a Buffer. +
PDFObject#readRawStream() +
Read the raw, uncompressed, contents of the stream object into a Buffer. +
PDFObject#writeObject(obj) +
Update the object the indirect reference points to. +
PDFObject#writeStream(buffer) +
Update the contents of the stream the indirect reference points to. +This will update the Length, Filter and DecodeParms automatically. +
PDFObject#writeRawStream(buffer) +
Update the raw, uncompressed, contents of the stream the indirect reference points to. +This will update the Length automatically, but leave the Filter and DecodeParms untouched. +
+ +

+PDF Page Access +

+ +

+All page objects are structured into a page tree, which defines the order the pages appear in. + +

+
PDFDocument#countPages() +
Number of pages in the document. +
PDFDocument#findPage(number) +
Return the page object for a page number. The first page is number zero. +
PDFDocument#deletePage(number) +
Delete the numbered page. +
PDFDocument#insertPage(at, page) +
Insert the page object in the page tree at the location. If 'at' is -1, at the end of the document. +
+ +

+Pages consist of a content stream, and a resource dictionary containing all of the fonts and images used. + +

+
PDFDocument#addPage(mediabox, rotate, resources, contents) +
Create a new page object. Note: this function does NOT add it to the page tree. +
PDFDocument#addSimpleFont(font) +
Create a PDF object from the Font object as a WinAnsiEncoding encoded simple font. +
PDFDocument#addFont(font) +
Create a PDF object from the Font object as an Identity-H encoded CID font. +
PDFDocument#addImage(image) +
Create a PDF object from the Image object. +
+ +

+TODO +

+ +

+There are several areas in MuPDF that still need bindings to access from JavaScript: + +

+ +

+Copyright © 2016 Artifex Software + + -- cgit v1.2.3