<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>PDFMiner</title>
<style type="text/css"><!--
blockquote { background: #eeeeee; }
--></style>
</head><body>
<h1>PDFMiner</h1>
<p>
Python PDF parser and analyzer
<p>
<a href="http://www.unixuser.org/~euske/python/pdfminer/index.html">Homepage</a>
<a href="#changes">Recent Changes</a>
<div align=right class=lastmod>
<!-- hhmts start -->
Last Modified: Sat Apr 4 09:14:28 JST 2009
<!-- hhmts end -->
</div>
<a name="intro"></a>
<hr noshade>
<h2>What's It?</h2>
<p>
PDFMiner is a suite of programs that aims to help
analyzing text data from PDF documents.
It includes a PDF parser, a PDF renderer
(though only rendering text is supported for now),
and a couple of nice tools to extract texts.
Unlike other PDF-related tools, it allows to obtain
the exact location of texts in a page, as well as
other layout information such as font size or font name,
which could be useful for analyzing the document.
<p>
<strong>Features:</strong>
<ul>
<li> Written entirely in Python. (for version 2.5 or newer)
<li> PDF-1.7 specification support.
<li> Non-ASCII languages and vertical writing scripts support.
<li> Various font types (Type1, TrueType, Type3, and CID) support.
<li> Basic encryption (RC4).
<li> PDF to HTML conversion (with a sample converter web app).
<li> Outline (TOC) extraction.
<li> Tagged contents extraction.
<li> Infer text running by using clustering technique.
</ul>
<a name="source"></a>
<p>
<strong>Download:</strong><br>
<a href="http://www.unixuser.org/~euske/python/pdfminer/pdfminer-dist-20090330.tar.gz">
http://www.unixuser.org/~euske/python/pdfminer/pdfminer-dist-20090330.tar.gz
</a>
(1.8Mbytes)
<p>
<strong>Discussion:</strong><br>
<a href="http://groups.google.com/group/pdfminer-users/">
http://groups.google.com/group/pdfminer-users/
</a>
<P>
<strong>View the source:</strong><br>
<a href="http://code.google.com/p/pdfminerr/source/browse/trunk/pdfminer">
http://code.google.com/p/pdfminerr/source/browse/trunk/pdfminer
</a>
<P>
<strong>Online Demonstration:</strong> (pdf -> html conversion webapp)<br>
<a href="http://pdf2html.tabesugi.net:8080/">
http://pdf2html.tabesugi.net:8080/
</a>
<a name="install"></a>
<hr noshade>
<h2>How to Install</h2>
<p>
<strong>Note:</strong>
This software is not yet out-of-the-box.
You have to download and unpack it manually,
and spend some time to make it work.
<strong>Your will</strong> is needed!
I do not support easy_install or setup.py or any automated installation until
this is very matured to the point that it really should be widely distributed.
(For now, it's not yet up to the standard, IMO.)
<ol>
<li> Install <a href="http://www.python.org/download/">Python</a> 2.4 or newer.
<li> Download the <a href="#source">PDFMiner source</a>.
<li> Extract it.
<li> Go to the <code>pdfminer</code> directory.
<li> Do the following test:<br>
<blockquote><pre>
$ <strong>python pdflib/pdf2txt.py samples/simple1.pdf</strong>
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ascii">
</head><body>
<div style="position:absolute; top:50px;"><a name="1">Page 1</a></div><span style="position:absolute; border: 1px solid gray; left:0px; top:50px; width:612px; height:792px;"></span>
<span style="position:absolute; writing-mode:lr-tb; left:100px; top:224px; font-size:22px;"> </span>
<span style="position:absolute; writing-mode:lr-tb; left:106px; top:224px; font-size:22px;">Hello </span>
<span style="position:absolute; writing-mode:lr-tb; left:168px; top:224px; font-size:22px;">World </span>
<span style="position:absolute; writing-mode:lr-tb; left:100px; top:124px; font-size:22px;"> </span>
<span style="position:absolute; writing-mode:lr-tb; left:206px; top:124px; font-size:22px;">Hello </span>
<span style="position:absolute; writing-mode:lr-tb; left:368px; top:124px; font-size:22px;">World </span>
<div style="position:absolute; top:0px;">Page: <a href="#1">1</a></div>
</body></html>
</pre></blockquote>
<li> Done!
</ol>
<p>
<h3>For non-ASCII languages</h3>
In order to handle non-ASCII languages (e.g. Japanese),
you need to install an additional data called <code>CMap</code>,
which is distributed from Adobe.
<p>
Here is how:
<ol>
<li> Get
<a href="http://www.unixuser.org/~euske/pub/CMap.tar.bz2">
http://www.unixuser.org/~euske/pub/CMap.tar.bz2
</a>
<li> Do the follwoing:
<blockquote><pre>
$ <strong>tar jxf CMap.tar.bz2</strong>
</pre></blockquote>
<li> Put the <code>CMap</code> directory into the <code>pdfminer</code> directory.
<li> Go to the <code>pdfminer</code> directory.
<li> Do the follwoing: (this is optional but highly recommended)<br>
<blockquote><pre>
$ <strong>make cdbcmap</strong>
</pre></blockquote>
</ol>
<a name="usage"></a>
<hr noshade>
<h2>How to Use</h2>
<p>
PDFMiner comes with two programs:
<code>pdf2txt.py</code> and <code>dumppdf.py</code>.
<a name="pdf2txt"></a>
<h3>pdf2txt.py</h3>
<p>
<code>pdf2txt.py</code> extracts text contents from a PDF file.
It extracts all the texts that are to be rendered programatically.
It also extracts the corresponding locations, font names,
and font sizes for each text portion. However,
it cannot extract texts embedded within images
(i.e. it does not do optical character recognition).
You can provide a password for protected PDF documents
whose access is limited.
<p>
For non-ASCII languages, you can specify the output encoding
(such as UTF-8).
Note that not all characters in a PDF can be converted safely
to Unicode, as some of them are not included in the current
Unicode Standard.
<p>
Examples:
<blockquote><pre>
$ <strong>python -m pdflib.pdf2txt -o output.html samples/naacl06-shinyama.pdf</strong>
(extract text as an HTML file whose filename is output.html)
$ <strong>python -m pdflib.pdf2txt -c euc-jp samples/jo.pdf</strong>
(extract Japanese texts in vertical writing, CMap is required)
$ <strong>python -m pdflib.pdf2txt -P mypassword secret.pdf</strong>
(extract texts from an encrypted PDF file with a password)
</pre></blockquote>
<p>
Options:
<dl>
<dt> <code>-o <em>filename</em></code>
<dd> Specifies the output file name.
By default, it prints the extracted contents to stdout.
<p>
<dt> <code>-p <em>pageno[,pageno,...]</em></code>
<dd> Specifies the comma-separated list of the page numbers to be extracted.
Page numbers are starting from one.
By default, it extracts texts from all the pages.
<p>
<dt> <code>-c <em>codec</em></code>
<dd> Specifies the output codec for non-ASCII texts.
<p>
<dt> <code>-w</code>
<dd> Split each word into a different chunk in the output.
This makes the word spacing correctly handled.
<p>
<dt> <code>-t <em>type</em></code>
<dd> Specifies the output format. The following formats are currently supported.
<ul>
<li> <code>html</code> : HTML format. (Default)
<li> <code>text</code> : TEXT format.
<li> <code>sgml</code> : SGML format.
<li> <code>tag</code> : "Tagged PDF" format. A tagged PDF has its own contents annotated with
HTML-like tags. pdf2txt tries to extract its content streams rather than inferring its text locations.
Tags used here are defined in the PDF specification (See §10.7 "<em>Tagged PDF</em>").
</ul>
<p>
<dt> <code>-P <em>password</em></code>
<dd> Provides the user password to open the PDF file.
<p>
<dt> <code>-d</code>
<dd> Increases the debug level.
</dl>
<a name="dumppdf"></a>
<h3>dumppdf.py</h3>
<p>
<code>dumppdf.py</code> dumps the internal contents of a PDF file
in pseudo-XML format. This program is primarily for debugging purpose,
but it's also possible to extract some meaningful contents
(such as images).
<p>
Examples:
<blockquote><pre>
$ <strong>python -m tools.dumppdf -a foo.pdf</strong>
(dump all the headers and contents, except stream objects)
$ <strong>python -m tools.dumppdf -T foo.pdf</strong>
(dump the table of contents)
$ <strong>python -m tools.dumppdf -r -i6 foo.pdf > pic.jpeg</strong>
(extract a JPEG image)
</pre></blockquote>
<p>
Options:
<dl>
<dt> <code>-a</code>
<dd> Instructs to dump all the objects.
By default, it only prints the document trailer (like a header).
<p>
<dt> <code>-p <em>pageno</em></code>
<dd> Specifies the page number to be extracted.
Multiple <code>-p</code> options are allowed.
Note that page numbers start from one.
<p>
<dt> <code>-r</code> (raw)
<dt> <code>-b</code> (binary)
<dt> <code>-t</code> (text)
<dd> Specifies the output format of stream contents.
Because the contents of stream objects can be very large,
they are omitted when none of the options above is specified.
<p>
With <code>-r</code> option, all the stream contents are dumped without decoding.
With <code>-b</code> option, the contents are dumped as a binary blob.
With <code>-t</code> option, the contents are dumped in a text format,
similar to <code>repr()</code> manner. When
<code>-r</code> or <code>-b</code> option is given,
no stream header is displayed for the ease of saving it to a file.
<p>
<dt> <code>-P <em>password</em></code>
<dd> Provides the user password to open the PDF file.
<p>
<dt> <code>-d</code>
<dd> Increases the debug level.
</dl>
<a name="changes"></a>
<hr noshade>
<h2>Changes</h2>
<ul>
<li> 2009/03/30: Text output mode added.
<li> 2009/03/25: Encoding problems fixed. Word splitting option added.
<li> 2009/02/28: Robust handling of corrupted PDFs. Thanks to Troy Bollinger.
<li> 2009/02/01: Various bugfixes. Thanks to Hiroshi Manabe.
<li> 2009/01/17: Handling a trailer correctly that contains both /XrefStm and /Prev entries.
<li> 2009/01/10: Handling Type3 font metrics correctly.
<li> 2008/12/28: Better handling of word spacing. Thanks to Christian Nentwich.
<li> 2008/09/06: A sample pdf2html webapp added.
<li> 2008/08/30: ASCII85 encoding filter support.
<li> 2008/07/27: Tagged contents extraction support.
<li> 2008/07/10: Outline (TOC) extraction support.
<li> 2008/06/29: HTML output added. Reorganized the directory structure.
<li> 2008/04/29: Bugfix for Win32. Thanks to Chris Clark.
<li> 2008/04/27: Basic encryption and LZW decoding support added.
<li> 2008/01/07: Several bugfixes. Thanks to Nick Fabry for his contribution.
<li> 2007/12/31: Initial release.
<li> 2004/12/24: Start writing the code out of boredom...
</ul>
<a name="related"></a>
<hr noshade>
<h2>Related Projects</h2>
<ul>
<li> <a href="http://pybrary.net/pyPdf/">pyPdf</a>
<li> <a href="http://www.foolabs.com/xpdf/">xpdf</a>
<li> <a href="http://www.pdfbox.org/">pdfbox</a>
</ul>
<a name="license"></a>
<hr noshade>
<h2>Terms and Conditions</h2>
<p>
<small>
Copyright (c) 2004-2009 Yusuke Shinyama <yusuke at cs dot nyu dot edu>
<p>
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
<p>
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
<p>
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</small>
<hr noshade>
<address>Yusuke Shinyama</address>
</body>
f628c0d3fe