Image Export Plug In

An Eclipse plug in to to simplify the task of exporting images from GEF diagrams.

Its goal is to allow exporting GEF diagrams to “images” in several formats in a generic and extensible way. It contributes two “Diagram Image” export wizards and allows for other plug ins to contribute diagrams to export (the “figure providers”) and image formats (the “image exporters”) to generate images. It is made that modular because we wanted it to be extensible. Plus we use existing libraries to generate certain formats (e.g. the Batik SVG Toolkit to produce SVG). Those libraries tend to be big and I wanted to let the user choose what formats are needed (there are still people with slow/dialup connections :>).

If there is no figure provider registered for a diagram file to be exported, we just open it in an editor and query the editor for the figure. This has the ugly side effect that editors open and close during the export operation. But at least you can export GEF diagrams you have editors for. This works for the GEF examples, see the screenshots and exported samples below. However, it does not work for multi page editors (it only works for the default page).

There are two wizards. One allows you to export images for several diagram files at once. You pick the files and the image format and all files are exported. The other wizard allows you to export an image of the current diagram. Optionally, you can choose to only export the current selection. There is even a preview that shows you how your image will look like. See the following screenshots.

Supported Formats

BMP, JPEG, PNG

Standard formats always included. (Seem to be the only formats SWT has proper write support for.) Support for PNG was first included in 0.10.0, which requires Eclipse 3.3, which is the first release to include write support for PNG.

• Sample exported JPEG
• Sample exported JPEG for the Shapes Example
• Sample exported JPEG for the Flow Example

PDF

Separate plug in de.unikassel.imageexport.pdf using the GMF renderer and iText.

• Sample exported PDF
• Sample exported PDF for the Shapes Example
• Sample exported PDF for the Flow Example

SVG

Separate plug in de.unikassel.imageexport.svg using the GMF renderer and the Batik SVG Toolkit.

• Sample exported SVG
• Sample exported SVG for the Shapes Example
• Sample exported SVG for the Flow Example

EPS

Separate plug in de.unikassel.imageexport.eps using Apache XML Graphics Commons. As you can see from the samples below, there are problems with bitmap graphics. Furthermore, generated EPS files have the line 0 setmiterlimit in them which makes Ghostscript barf. A simple sed -i -e 's/0 setmiterlimit//' diagram.eps removes the lines and everything seems to be fine.

• Sample exported EPS
• Sample exported EPS for the Shapes Example
• Sample exported EPS for the Flow Example

Download and Installation

As this is a spin-off project from my still unreleased Janus project, I placed the files on its download page so it is at least no longer empty :). This is a release from two persons making their first experiences with the Eclipse platform so you should expect to meet bugs all along the way. Comments, discussion, patches and everything else is welcome. Please use the facilities provided by Sourceforge, i.e. the trackers and forums.

What and Where?

Downloadable files are on the SourceForge files page.

Download the Image Export Plug In and all the export format plug ins you are interested in (currently there are additional plug ins for PDF, EPS and SVG). If you install the PDF, EPS or SVG export plug ins, you also need the GMF plug-in. You can install this by selecting "Help > Software Updates > Find and Install...", and choose to install "new features" from the "Europa Discovery Site". GMF has a lot of dependencies of its own so "Select Required" often comes in handy.

For SVG, you additionally need the Batik plug in. For PDF, you also need the iText plug-in. Both can be installed like GMF (see above, have a look at the section called "Enabling Features"). For EPS, a plug-in for Apache XML Graphics Commons is provided.

You also need one of the logging plug ins (if you do not already have installed a plug in that provides the org.slf4j package). If you are not interested in logging output or do not know what I am talking about, download the org.slf4j.nop plug in which throws away all logging output. If you experience errors or find bugs, you might want to install the org.apache.nlog4j plug in and post the output in the forums.

See the Releases page for an overview.

Unpack the Image Export Plug In into your Eclipse installation directory and copy the additional export format plug ins and the logging plug in into your plugins directory. When restarting Eclipse, you should see the Image Export feature and plug ins in Help > About Eclipse SDK > Feature Details / Plugin Details.

Eclipse 3.4's dropins directory improves the installation process of plug-ins. See Equinox p2 cures Eclipse plug-in headaches on IBM's developerWorks.

Getting Logging Output

When using the nlog4j plug in you might want to start Eclipse with something like -Dlog4j.configuration=file:/path/to/log4j-config.xml. Another useful one might be -Dlog4j.debug=true.

A complete example command line (all in one line):

./eclipse -data ../workspace -clean -debug -consolelog -vmargs \ -Dlog4j.configuration=file:/home/thm/.imageexport/log4j-config.xml \ -Dlog4j.debug=true

Known Bugs and Missing Things

• I have to turn antialiasing off because Cairo crashes my Eclipse (see my posting). To be precise, I must not touch the antialiasing setting to prevent that Cairo is used. On MacOSX things are antialiased by default.
• Export operation does not honour directory structure related stuff. Images are exported where the diagrams are, with the file extension replaced by the format's extension (e.g. “foo.bar” is exported to “foo.jpeg”).
• I wanted to provide sample figure providers for the GEF example editors (shapes, logic, etc.), but unfortunately the example plug ins do not reexport their packages. And they probably shouldn't, because they are not API. But it would have been nice. Update: fortunately, Randy Hudson suggested contributing the Image Export code to GEF. I have to polish the code a bit, but that is a motivating perspective. Well, it was, but unfortunately GEF development seems to have low priority. Nobody followed up on my report since March 2007.

Technical Stuff, Rationale

To export a GEF diagram you need to

1. Load the model file.
2. Render it to the desired format and save it.

It is impossible to implement loading the model in a generic way because each model is different. So people who would like to use the export plug in have to give it something more universal. Eventually, each model displayed in a graphical viewer is displayed as a figure, so an IFigure is used.

The figure can be told to paint itself, passing it a Graphics argument. So by using SWTGraphics or writing other Graphics adapters, the rendering to another format can be done transparently.

User Interface

To seamlessly plug into Eclipse I thought it would be nice if the user was able to choose File > Export..., select “Diagram Image” from the list of export engines and was presented with a typical export wizard that allows choosing which files to export into which target directory and so on. So the Image Export contributes such a wizard. The user may activate this wizard as soon as the Image Export plug in is installed.

Architecture

Each client that wants to contribute a model format to the export wizard, registers a FigureProvider at the Image Export plug in. Figure providers know how to load “their” kind of model, create a GraphicalViewer, set an EditpartFactory and so on and finally get the root figure. Figure providers register the file types they understand and get asked by the export wizard to provide a figure for a model file the user selected to export.

Then there are ImageExporters that know how to render an IFigure to the format they export to and save the result to a file. They also register at the Image Export plug in. When the user calls the image export wizard, the user can choose one of the registered formats from a combo box.

I did all that to keep the plug in dependencies down to a minimum. Your own editor that wants to contribute to the export wizard may provide a FigureProvider and optionally depend on the Image Export plug in. That means that it will register at the Image Export plug in if that is installed and that nothing will happen if it is not installed.

The exporter plug ins depend on the Image Export plug in. The user chooses which formats he wants to be able to export to and installs exactly the ones needed.