FOray: Using Graphics

Contents

• Overview of Graphics Support
• BMP
• JPEG
• PNG
• TIFF
• EPS
• SVG
  • Introduction
  • Placing SVG Graphics into PDF
  • Placing SVG Text into PDF
  • Scaling
  • Known Problems
• Resolution
• Caching
• Graphic Sources

Overview of Graphics Support

The table below summarizes the support for graphical formats within FOray. Known limitations and other qualifications for each type of graphic are noted in the corresponding sections below.

BMP

FOray native support for BMP images is limited to the RGB color-space.

JPEG

JPEG support may not include all variants, especially those containing unusual color lookup tables and color profiles. If you have trouble with a JPEG image in FOray, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it. Specifying 24-bit color output may also help. User reports indicate that grayscale, RGB, and CMYK color-spaces are all rendered properly.

PNG

Only RGB and RGBA color-spaces are supported.

TIFF

TIFF support is currently limited to PDF and PostScript output only. Also, according to user reports, TIFF images must have all of the following characteristics for successful rendering:

• uncompressed images, or images using CCITT T.4, CCITT T.6, or JPEG compression
• images using white-is-zero encoding in the TIFF PhotometricInterpretation tag

EPS (Encapsulated PostScript)

FOray provides support for two output targets:

• PostScript (full support).
• PDF (partial support). Starting with release 0.3, FOray includes a partially-implemented built-in PostScript interpreter and support for converting supported PostScript input to PDF output. The current implementation covers enough of the PostScript operators to support many simple graphics. FOray logs unsupported PostScript operators so that you can see which operators are included in the input that are not supported by FOray. If you need support for additional PostScript operators, enquire on the user mailing list.

SVG

Introduction

SVG content can be included as either an fo:instream-foreign-object or in a separate file referenced with fo:external-graphic.

FOray uses the Apache Software Foundation's Batik for SVG support, and includes the Batik jar files in its distribution. The version of Batik used is included in the jar file name(s) in the lib directory. Because Batik's API changes from time to time, best results will be obtained by using the version that ships with FOray when running FOray.

Batik must be run in a graphical environment.

Batik must be run in a graphical environment. It uses AWT classes for rendering SVG, which in turn require an X server on Unixish systems. If you run a server without X, or if you can't connect to the X server due to security restrictions or policies (a so-called "headless" environment), SVG rendering will fail. Here are some possible workarounds:

• Start the Java Virtual Machine with the -Djava.awt.headless=true command line option.
• Install an X server which provides an in-memory framebuffer without actually using a screen device or any display hardware. One example is Xvfb.
• Install a toolkit which emulates AWT without the need for an underlying X server. One example is the PJA toolkit, which is free and comes with detailed installation instructions.

Placing SVG Graphics into PDF

The SVG is rendered into PDF by using PDF commands to draw and fill lines and curves. This means that the graphical objects created with this remain as vector graphics.

There are a number of SVG things that cannot be converted directly into PDF. Parts of the graphic such as effects, patterns and images are inserted into the PDF as a raster graphic. The resolution of this graphic may not be ideal depending on the FOray dpi (72dpi) and the scaling for that graphic. We hope to improve this in the future.

Currently transparency is not supported in PDF so many svg images that contain effects or graphics with transparent areas will not be displayed correctly.

Placing SVG Text into PDF

If the text can be drawn normally and the font is supported, Batik uses normal PDF text support. Note that tspan and outlined text are not yet implemented.

Otherwise, text is converted and drawn as a set of shapes by batik, using the stroking text painter. This means that a typical character will have about 10 curves (each curve consists of at least 20 characters). This can make the pdf files large and when the pdf is viewed the viewer does not normally draw those fine curves very well (turning on Smooth Line Art in the Acrobat preferences will fix this). If the text is inserted into the PDF using the inbuilt text commands for PDF it will use a single character.

For PDF output, there is a configuration option to force SVG text to be rendered as text. The drawback to this approach is that it is effective only for available fonts (including embedded fonts). Font sizes are rounded to the next integer point size. This will be improved in the future.

Note that because SVG text can be rendered as either text or a vector graphic, you may need to consider settings in your viewer for both. The Acrobat viewer has both "smooth line art" and "smooth text" settings that may need to be set for SVG images to be displayed nicely on your screen (see Edit / Preferences / Display). This setting will not affect the printing of your document, which should be OK in any case, but will only affect the quality of the screen display.

Scaling

Currently, SVG images are rendered with the dimensions specified in the SVG file, within the viewport specified in the fo:external-graphic element. For everything to work properly, the two should be equal. The SVG standard leaves this issue as an implementation detail. FOray will probably implement a scaling mechanism in the future.

Known Problems

• soft mask transparency is combined with white so that it looks better on pdf 1.3 viewers but this causes the soft mask to be slightly lighter or darker on pdf 1.4 viewers
• there is some problem with a gradient inside a pattern causing a pdf error when viewed in acrobat 5
• text is not always handled correctly, it may select the wrong font especially if characters have multiple fonts in the font list
• more pdf text handling could be implemented It could draw the string using the attributed character iterator to handle tspans and other simple changes of text.
• JPEG images are not inserted directly into the pdf document This area has not been implemented yet since the appropriate method in batik is static
• Uniform transparency for images and other svg elements that are converted into a raster graphic are not drawn properly in PDF. The image is opaque.

MathML (Mathematical Markup Language)

FOray supports MathML documents in fo:external-graphic, using JEuclid. Current repository code supports and future releases will support MathML documents within fo:instream-foreign-object also.

Resolution

Some bitmapped image file formats store a dots-per-inch (dpi) or other resolution value. Since PDF and most output formats do not have a concept of resolution, but only of absolute image units (i.e. pixels) FOray ignores the resolution values as well. Instead, FOray uses the dimensions of the image as specified in the fo:external-graphic element to render the image:

• If no dimensions are given, FOray uses a default value of 96 dpi to compute the graphic's dimensions. For example, suppose a graphic 300 pixels wide and 400 pixels high. FOray will render the graphic at 3.125 inches wide, 4.167 inches high, with an apparent resolution of 96 dpi.
• If only one dimension is given, FOray by default uses the same aspect ratio to compute the other dimension (to avoid the appearance of stretching). For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = ".5in". FOray will compute the content-height = .667 inches, and will render the graphic at that size, with an apparent resolution of 600 dpi.
• If both dimensions are given, FOray simply renders the image in that space. For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = "3in" and content-height = "4in". FOray will render the graphic at that size, with an apparent resolution of 100 dpi.

If you need a higher apparent output resolution for bitmapped images, first make sure that at least one dimension of the image is defined in your XSL-FO input. Apart from that, resolution problems are in the image file itself, and must be corrected there: use or create a higher-resolution image file.

The explanation above describes only the basic default behavior. There are other attributes of the fo:external-graphic element that can affect the behavior described above.

Caching

FOray caches images between runs. The URL is used as a key to identify images which means that when a particular URL appears again, the image is taken from the cache. If you have a servlet that generates a different image each time it is called with the same URL you need to use a constantly changing dummy parameter on the URL to avoid caching.

Currently, graphics are not automatically released when an OutOfMemoryError is imminent. The cache can grow to a considerable size over time when a lot of different URLs are in use. You can call org.foray.graphic.GraphicServer.resetCache() to manually empty the cache.

Graphic Sources

For graphic-related properties (background-image and src), the <uri-specification> provided is resolved in the following order:

1. If the URI is an absolute path, that path is used.
2. A path relative to the “document directory” is tried next. The document is the fo or xml file, if any, that was presented on the command-line. This value is not automatically set for documents not run from the command-line, because there is not necessarily a URI associated with the document.
3. A path relative to the base-directory is tried next.
4. A path relative to the current directory as reported by the operating system is tried next.