Notes On Output Formats

In ChartDirector, certain chart types, such as surface charts, 3D scatter charts and 3D pyramids and cones, are based on true 3D graphics technology. For example, curved surfaces are created with many triangles. Textures on the triangles (such as the color bands in surface charts) are transformed to a suitable view angle and perspective. There are also 3D lighting effects.

SVG and PDF are essentially 2D vector graphics formats. To output 3D graphics, ChartDirector must use many 2D graphics instructions to emulate a 3D graphics instruction. For example, in the Surface Chart (1) sample code, the surface is created with 12800 triangles. To translate into SVG or PDF, it would need several times the number of gradients for proper shading and lighting of the triangles. The resulting SVG or PDF would be quite large in file size. It can be very slow when displayed on a SVG or PDF viewer, if the viewer can handle it at all.

The above issue only affects 3D charts with curved surfaces composed with many triangles. It does not affect surface chart which only uses a few triangles (configurable with SurfaceChart.setInterpolation), or using wireframes instead of surfaces. It also does not affect 3D scatter charts, which does not have curved surface. It moderately affects 3D cones, which use triangles but not in a very large number.

Another issue in using SVG or PDF for 3D graphics is that most SVG or PDF viewers cannot combine shapes seamlessly. If a shape is composed of multiple triangles, the boundary among the triangles are often visible as very thin lines. When you zoom-in the shapes, these very thin lines will always be very thin and will not become thicker. This shows that these very thin lines are artifacts created by the viewer and does not actually exists in the graphics. They are caused by the anti-alias algorithm commonly used in 2D graphics.

If your application must output SVG, and the above issues are a concern, you may consider to output the charts as raster graphics (bitmaps) and embed them in SVG. This can be achieved using BaseChart.setOutputOptions. The raster graphics will be rendered by ChartDirector, which can handle 3D graphics properly. The drawback is that the output is essentially raster graphics, though in a SVG container.

For historical reasons, ChartDirector includes certain low level raster only graphics primitives. Examples are DrawArea.pixel and DrawArea.getPixel which sets and gets a pixel from the frame buffer of the image, DrawArea.fill2 and DrawArea.fill2 which perform flood filling, and various non-affine transform functions. These functions have no effect in vector graphics formats such as SVG and PDF, and should not be used with these formats.

ChartDirector does not use any raster only graphics primitive, so they will not affect charts created by ChartDirector. The above would only be a concern if your code is using the DrawArea object for custom drawing and the output is in a vector graphics format such as SVG or PDF.

When creating PDF, it is common to embed the fonts into the PDF output. In this way, the viewing computer can display the contents even if the computer does not have the necessary fonts installed.

To embed a font in PDF, ChartDirector needs to know the path of the font file. However, in ColdFusion, a font is often specified using the font family name and style, not the filename. For example, "Verdana Bold Italic" can be used to specify a font instead of "verdanaz.ttf". There is no ColdFusion API that can determine the filename from the "family name". To locate the font file, on Windows and Mac OS X, ChartDirector will try to guess the font filename from the family name. If this is not successful, ChartDirector will scan the operating system font directories to create a map of font family names to filenames, then use the map to resolve the font filename.

On Linux or many other operating systems, there is no standard font directory. In this case, ChartDirector will scan the directories specified in the "cd.fontpath" property if available. This property can be set using the "-D" flag in the Java command line that starts up ColdFusion.

The following points can ensure ChartDirector can find the font files:

On systems that is not using Windows or Mac OS X, set up the "cd.fontpath" property to list out the font directories that contains the fonts available in Java.
Use font filename to specify the font instead of font family names and styles. In this way, ChartDirector would not need to map from the family name to the filename.
Do not use "logical fonts", such as "Dialog" or "SanSerif". These fonts are synthesized dynamically by Java from one or more real fonts, which can be different for different systems. They cannot be embedded in PDF.

ChartDirector PDF currently only supports true type fonts (.ttf), including true type font collections (.ttc) and open type fonts (.otf) with true type outlines. If a non-supported font is used, or if the font file cannot be found, it will be substituted with one of the 14 standard PDF fonts. According to the Adobe PDF standard, all PDF viewers should contain 14 standard fonts, and so no embedding is needed. The 14 standard fonts are the 4 variants (normal, bold, italic/oblique and bold-italic/bold- oblique) of the Times, Helvetica and Courier typeface, as well as the Symbol and ZapfDingbats fonts. These fonts only support characters defined in the WinAnsiEncoding.