brandonheller / pv_export Goto Github PK

pv_export: a simple tool to create PDFs from Protovis source
Brandon Heller <[email protected]>

Derives from code by Jamie Love, posted to Protovis mailing list: http://groups.google.com/group/protovis/browse_thread/thread/ee5737796b4235eb/2e2af35c583504fd

------------------------------------------------------------------------------
OVERVIEW:
Protovis produces beautiful vector output, but it's normally confined to the
browser.  Yeah, you could manually use print-to-PDF from a web browser, or
you could script a particular web browser to do PDF output given an HTML
file, and you'd get PDF output.  I want a method for generating PDFs that is:
- non-browser-dependent
- non-OS-dependent
- easy to install (doesn't require compilation)
- easy to automate

pv_export tries to achieve these properties, by combining a bunch of open-
source libraries and providing an easier interface on top of them.  Includes:
- Rhino: JavaScript interpreter
- envJS: a browser environment in JavaScript
- Batik: library for vector graphics

------------------------------------------------------------------------------
HOW TO RUN:
Ensure you have a JDK v1.6 or later (Sun or OpenJDK).  Then run:

> ./pv_export.py

This should generate pv_linechart_test.pdf w/a sample line chart, in the
directory where pv_export.py was called.

To see a help screen with the available params:

> ./pv_export.py -h

Usually, the only modification needed to a Protovis example is to modify the
Panel() creation by appending ".canvas('fig')", so that the SVG gets created
for the Panel.  This is how the examples/{area.html/area.js} example works.

  var vis = new pv.Panel()
      ...

... must be changed to:

  var vis = new pv.Panel().canvas('fig')
      ...

If you don't want to use 'fig' for the HTML div name, you can pass in a
different one with the --div option.

MONOLITHIC HTML MODE
If the HTML file includes the figure-creating script and data file, then to
run this, just pass in the HTML file on the command line and an output file
path:

> cd examples
> ../pv_export.py --html area.html -o area.pdf

This is the fastest way to get going and start from examples, BUT debugging
can be much harder because the standard way to handle JavaScript errors is to
ignore them silently in HTML.  Sometimes a typo or logic error will cause
Protovis not to render anything, and you'll be stuck.  Raw JavaScript mode
doesn't have this problem, and conveniently shows line numbers for all
JavaScript errors encountered.

RAW JAVASCRIPT MODE
Alternately, you can use pv_export in a raw mode with a figure and data file,
and a blank HTML document will be used.  To run the raw version of the
previous one, specify the vis and data .js files:

> cd examples
> ../pv_export.py -v area_bare.js -d area_data.js -o area_bare.pdf

------------------------------------------------------------------------------
KNOWN BUGS:
(*) Can't change label font.
This appears due to limitations in envJS's implementation of SVG/CSS.  If you
attempt to add this property to Label:

 .font("12px sans-serif")

... you're likely to get an error.

(*) Can't run full matrix example.
Rhino runs out of heap space and crashes after awhile.  Fix unknown.

See for more details:
http://groups.google.com/group/protovis/browse_thread/thread/d011750dd3428ddd