This document describes the enhancements and bug fixes in ChartDirector Ver 5.0 comparing to ChartDirector Ver 4.1. For enhancements in earlier versions of ChartDirector, please refer to the release notes archive.

3D Surface Chart is a new chart type in ChartDirector Ver 5.0. It accepts (x, y, z) points as input, and computes a surface that fits the points using linear or spline surface interpolation. It then draws the surface in 3D and colors the surface based on the z value.

The key features are:

• Supports both gridded data and scattered data.
• The x, y and z axes can be numeric, date/time, or enumerated (label based).
• Supports linear and spline surface interpolation for producing smooth surfaces.
• Configurable elevation and rotation angles.
• Configurable perspective effects.
• Configurable ambient, diffuse and specular lighting effects.
• The front and back sides of the surface can use different lighting effects.
• Supports continuous and discrete coloring of z levels.
• Configurable grid and contour lines on the surface. Line styles and custom mark lines are supported.
• Supports rendering of wireframes.
• Configurable walls for the 3D plot region.

Pyramid/Cone/Funnel Charts are new chart types in ChartDirector Ver 5.0. Like a pie chart, they are mainly used for visualizing relative magnitudes. But instead of using a pie, a pyramid, cone or funnel is used. The pyramid, cone or funnel is sliced horizontally into layers, with the layer height proportional to the data value.

The key features are:

• Supports 2D and 3D view.
• Configurable elevation and rotation angles.
• Configurable gradient shading.
• Configurable ambient, diffuse and specular lighting effects.
• Configurable layer gap.
• Labels at the left, right and center of the layers

Contour Layer is a new layer type in XY charts. It accepts (x, y, z) points as input, and computes a surface that fits the points using linear or spline surface interpolation. It then colors the xy plan based on the z value of the surface, and draw contours to join points with the same z value.

The key features are:

• Supports both gridded data and scattered data.
• Supports linear and spline surface interpolation for producing smooth contours.
• Supports continuous and discrete coloring of z levels.
• Supports custom contour levels with line styles.

In additional to raster images, ChartDirector Ver 5.0 can output true vector graphics images in SVG and SVGZ (compressed SVG) formats.

ChartDirector Ver 5.0 adds a number of pie chart shading modes, including:

• Default Shading
• Flat Shading
• Local Gradient Shading
• Global Gradient Shading
• Concave Shading
• Rounded Edge Shading
• Radial Shading
• Ring Shading

In previous versions of ChartDirector, negative values in pie charts are not supported. For example, if the values are 2, -1, -1, the behaviour is undefined. If negative values are present, they must be converted to positive values before passing the data to pie chart.

Negative values are now supported in ChartDirector Ver 5.0. They are treated as if they are positive. For example, if the data values are 2, -1, -1, the pie will contain 3 sectors of 50%, 25%, 25%. The sector labels will still display the values as negative.

Each sector in a pie chart can now have a border of configurable color and thickness lying internal to the sector (and hence will not overlap with neighbouring sectors despite the thichness of the border).

Previous versions of ChartDirector support using linear regression to compute an optimal straight line that best fits a set of points. ChartDirector Ver 5.0 adds support for logarithmic, exponential, polynomial, and constrained linear regression (a linear regression that always passes through the origin). Like linear regression, these new types of regressions include confidence and prediction bands.

ChartDirector has always supported line and spline charts in which the lines and spline curves can flow in any direction (not limited to left to right). ChartDirector simply joins the data points with lines or spline curves in the order that the data points are passed to ChartDirector.

Due to the nature of splines, it is possible for a spline curve to "overshoot and flow back" for highly even data points. For data points that flow from left to right (which is the most common case), it may be undesirable if the curve overshoot in the horizontal direction (possible for data points with highly uneven horizontal spacing).

ChartDirector Ver 5.0 supports monotonic constraints for spline curves. For example, if the data points flow from left to right (monotonic in the horizontal direction), ChartDirector can ensure the spline curve also flows strictly from left to right (that is, never overshoots in the horizontal direction). The monotonic constraint can also be placed on the vertical direction, or on both directions.

CDML Table is a new text box container object introduced in ChartDirector Ver 5.0. Each cell in the table is a text box object, and can have independent background colors, rasied effects and font styles. A cell can span more than one row and/or column. The contents of the a cell can be specified using CDML (ChartDirector Mark Up Language), and so the cell can contain text as well as images.

A CDML Table can be created as a free floating object, or docked to an XY chart axis for containing the axis labels.

For a label based axis, ChartDirector can generate a CDML Table to contain the labels. The CDML Table will be docked to the axis. Rows and/or columns can be added to the table to display additional information.

A common application is to dock a CDML table under the x-axis, and add charting data as additional rows to the table. This creates a chart with the data values tabulated under the x-axis, which is a useful alternative to putting data labels directly on the bars or data points on the chart.

ChartDirector Ver 5.0 allows the legend icon that represents an XYChart data series to be retrieved as CDML (ChartDirector Mark Up Language) text. As text, it can be combined with other text, and put into various text containers (text box, CDML table, etc). For example, one can use this feature with a CDML table to create a custom legend box. Another common usage is to use the icon to label the data series in a CDML table docked under the x-axis.

ChartDirector supports two legend icon styles. Normally, the icons will be colored boxes representing the colors of the data sets. However, if the chart contains data lines with line styles, data symbols or if bar shapes are used, the legend icons will change to the extended style, which are wider and use more space, but can show the line styles (eg. dash line style), data symbols and bar shapes.

In some cases, line styles or data symbols are not used, but the user still wants to use extended style legend icons. In previous versions of ChartDirector, this can be achieved by using a "dummy dash line color" (eg. using a dash line style with mark and space being 1 and 0, which is equivalent to a solid line). In ChartDirector Ver 5.0, there is now an API specifically designed to switch on extended style icons.

Three new spherical symbols are data in ChartDirector Ver 5.0. Two of them are translucent glass spheres, one deeper and one brighter. The third symbol is a solid sphere. These symbols can be used in bubble charts to create impressive bubbles. They can also be used as data symbols in line or scatter charts.

Brushed Metallic Color is an enhancement to the standard metallic color by adding a subtle random horizontal texture effect. A surface painted with this color resembles a brushed metal surface. The strength of the brushed metal texture is confgurable.

The chart frame can now cast a soft or hard drop shadow. The direction, offset, color and softness of the shadow are configurable.

Gradient Bar Lighting is a new shading effect for rectagular and polygonal bars in a bar chart. It shades a bar with varying brightness along the length of the bar. For a 3D bar, it also shades the top surface of a vertical bar and the right surface of a horizontal bar with varying brightness along the depth dimension.

Previous versions of ChartDirector paint cylindrical bars with a built-in gradient color that gives the impression of a cylinder. ChartDirector Ver 5.0 introduces configurable and accurate Cylinder Bar Lighting, in which the brightness of the cylindrial surface is computed using the Phong lighting model with configurable ambient, diffuse and specular lighting.

In previous versions of ChartDirector, data labels for bars can be put at the far end of the bars (the far end is the end that is opposite to the baseline) or the center of the bars. In ChartDirector Ver 5.0, data labels can be put at any of the 9 alignment positions (top left, left, top right, left, center, right, bottom left, bottom, bottom right).

In previous versions of ChartDirector, for a bar or area chart, the bar or area always start from zero. If the zero position is outside the plot area, the bar or area will start from the border of the plot area that is closer to zero.

ChartDirector Ver 5.0 supports configurable baseline, which means the bar or area can start from any value. If the baseline is outside the plot area, the bar or area will start from the border of the plot area that is closer to the baseline.

For a bar chart or box-whisker chart (like a gantt chart), the hot spot region is the bar or box. If the bar or box is very small or zero in size, it is difficult or impossible to have mouse actions (eg. click or show tooltips) on it.

ChartDirector Ver 5.0 supports configurable minimum size for the hot spot. If the bar or box shrinks below the minimum size, the hot spot will stay at the minimum size, so the user can still have mouse actions on it easily.

In previous versions of ChartDirector, vectors in a vector layer are specified by their starting points, lengths, and angles. This type of vector specification is suitable for vectorial quantities, such as wind direction and electric field strength.

Sometimes vector layers are used to show relationships among points, rather than vectorial quantities. For example, a vector layer can be used to draw arrows to link pairs of points in a scatter layer, or to draw arrows along the line segments in a line layer.

For a vector used to link two points, sometimes it is not trivial to determine its length and angle from the (x, y) coordinates of the end points. It is because they also depends on the ratio between the x-axis and y-axis scales. If the axes are auto-scaled, tbe ratio may not be known in advance. Often, additional code is needed to query the axes scales, and take them into account when computing the length and angle.

In ChartDirector Ver 5.0, the vector layer is enhanced to allow vectors to be specified using the end points. This simplifies coding for cases in which vectors are used to link points.

When a vector is used to link between two points, it is sometimes desirable not to terminiate the vector at precisely the points. For example, the points may be denoted by circular symbols. Instead of terminating the vector at the center of the circles, it may be better to shorten the vector to terminate it at the rims of the circles.

ChartDirector Ver 5.0 supports specifying independent margins at the two end points of the vector, so that the vectors can be shortened or lengthened.

ChartDirector Ver 5.0 can automatically adjust the position and size of the XY chart plot area, so that the plot area, inclusive of axis labels, fits a given bounding box. This avoids the need to explicitly reserve sufficient space for the longest axis label, which is often unknown in advance.

In previous versions of ChartDirector, the position and size of an XY chart plot area is specified by user code. Therefore, the user code always knows the position and size of the plot area.

ChartDirector Ver 5.0 can automatically adjust the plot area position and size, so that the plot area, inclusive of the axis labels, fits a given bounding box. Because of this, the user code may no longer know the position and size of the plot area. New API are therefore added to allow the user code to retrieve these information.

There is now an API available to get the "thickness" of an XY chart axis (the width for a vertical axis, and the height for a horizontal axis). This simplifies positioning of other chart objects based on the thickness of the axis.

In previous versions of ChartDirector, the drawing order of the layers in an XY Chart is determined by the order that the layers are added to the chart, with the first layer in the front. Also, all layers are drawn on top of the grid lines.

In some cases, it may be desirable to draw a layer under the grid lines. An example is the newly introduced contour layer, which is natural to draw under the grid lines.

ChartDirector Ver 5.0 allows a layer to be inserted in front or behind another layer. It also allows the grid lines to be inserted in front of a given layer, instead of always behind all layers.

The followings are new features added to the finance chart library:

• Parabolic SAR indicator
• Price comparision line
• Percentage axis scale
• Configurable gaps between technical indicator charts.

In previous versions of ChartDirector, for a numeric axis, if no format is specified, the axis labels will be independently and automatically formatted. For example, an axis with scale 0 - 2 with a label every 0.5 unit will have labels like 0, 0.5, 1, 1, 1.5, 2.

In ChartDirector Ver 5.0, ChartDirector will analysis all label values to determine the precison required to distinguish the values. It will then apply the same format to all label values. In the example above, the precision is 1 decimal place, so the labels will be 0.0, 0.5, 1.0, 1.5, 2.0.

A new decimal place specifier "@" is added to allow a custom format string to specify this dynamically determined decimal place.

For a logarithmic scale axis, ChartDirector can automatically generate 3 types of ticks:

• Geometric ticks, like 1, 10, 100, 1000, 10000, ... These ticks are equally spaced in logarithmic scale.
• 1, 2, 5 ticks, like 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, ... These ticks are approximately equally spaced in logarithmic scale.
• Linear ticks, like 200, 210, 220, 230, 240, ... These ticks are approximately equally spaced only if the axis range is small (eg. the ratio of the maximum and minimum value is less than 3).

Other tick patterns are possible, but they need to be explicity specified by calling the ChartDirector API.

ChartDirector Ver 5.0 supports a new type of automatically generated ticks:

• Linear Decade Ticks: The ticks are linear within a decade, but the decades themselves grow geometrically. It is like 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 200, 300, .....

ChartDirector allows the axis labels or ticks to be offseted by an amount. This is often used for putting the axis labels between ticks (instead of centered at the ticks), which can be achieved by shifting either the labels or the ticks by half the tick increment.

However, for an auto-scaled axis, the tick increment may not be unknown in advance. So it may not be trivial to determine the amount to shift.

ChartDirector Ver 5.0 allows the shift to be specified in "tick increment" units, without having to know what is the tick increment. It also exposes a "{tickInc}" parameter for the tick increment, which can be used in axis label templates. This allows axis labels to show the range between the two ticks.

In ChartDirector Ver 5.0, a new numeric formatting method is added:

• Maximum number of decimal place (P format): The number will be rounded to at most N decimal place (N is configurable). It will contain less decimal place if they are not needed (eg. the number is an integer), or if the number already contains more than N significant digits.

With the P format, small numbers will have at most N decimal place, while large numbers may have less or no decimal place. Unlike the G format, it never uses to scientific formatting.

The following operating system / programming framework combinations are added in ChartDirector Ver 5.0.

• ChartDirector for C++ on FreeBSD (AMD64)
• ChartDirector for C++ on Solaris (x86)
• ChartDirector for Python on FreeBSD (AMD64)
• ChartDirector for Python on Solaris (x86)

---

---

The default colors and layouts are changed slightly in the FinanceChart object:

• The default plot area background color is now white instead of pale yellow.
  
  
• The default plot area border color is now grey instead of black.
  
  
• Instead of using a thick black line to separate two sub-charts, there is now a gap of 2 pixels (configurable) separating them. As a result, the total height of a FinanceChart may increase by a few pixels, depending on the number of sub-charts inside.

Earlier versions of ChartDirector on Mac OS X support specifying fonts using Mac OS X Font Manager names. However, since Nov 2007, in order to support the then new Mac OS X 10.5 (Leopard), ChartDirector for PHP and Perl were updated and no longer supports Mac OS X Font Manager names. The main reasons are:

• The Mac OS X Font Manager only works if someone has logged in the computer. This is not suitable for server, batch or cron applications, which often run even when no one has logged in. ChartDirector is often used in these types of applications.
  
  
• Since Mac OS X 10.5 (Leopard), Mac OS X no longer supports any forked process to use the Font Manager API. On the other hand, in Mac OS X, web servers almost always use forking to support concurrent requests. In other words, web applications can no longer use the Font Manager API, even if someone has logged in the computer.
  
  
• Since Mac OS X 10.5 (Leopard), the PHP that comes with Mac OS X has 64-bit support. ChartDirector was updated to support 64-bit too. But the Font Manager API that ChartDirector uses does not support 64-bit. (Although the Mac OS X core is 64-bit capable, many parts of the Mac OS X GUI are still 32-bit only.)
  
  
• Many people use Mac OS X as a development machine only. The production machine may be a different machine using a different operating system. To ensure code portability, it is better not to use Mac OS X Font Manager names.

Because of the above reasons, in ChartDirector Ver 5.0, Mac OS X Font Manager names support is removed in all Mac OS X editions of ChartDirector. Font file names should be used to specify the fonts instead. If the application must use Mac OS X Font Manager names, it needs to translate them to font file names using the relevant Mac OS X API, before passing the names to ChartDirector.

The followings are the list of bugs that are fixed in ChartDirector Ver 5.0.

• Loading of JPG images (eg. as background images) is broken in Mac OS X. (ChartDirector for Java is not affected by this issue.)
  
  
• Alpha channel is not saved correctly in PNG files in big-endian machines, such as Sparc or PowerPC based machines. (ChartDirector for Java are not affected by this issue.)
  
  
• Auto-scaling may choose a scale with a small positive value even if all data values are negative.
  
  
• If the axis scale contains both negative values and 0, and scientific formatting is used for the axis labels, the label at 0 may be displayed as an extremely small number due to rounding issues.
  
  
• The Java WebChartViewer may not generate the correct partial update callback URL if the original URL contains query parameters.
  
  
• The .NET WebChartViewer may handle partial update AJAX requests incorrectly if the server thread is not using the invariant or compatible cultures.
  
  
• Partial update AJAX requests may not work in IE 6 or below if secure HTTP (https) is used and ActiveX components are disabled.
  
  
• The '#' character (reserved character in URL) is not escaped in image maps generated by ChartDirector.
  
  
• For a multi-bar chart, even if the data sets use different axes, all the bars will still use the first axis to determine the baseline (usually the y = 0 line). This may cause issues if the baselines of the axes are not aligned.
  
  
• If a mark line is outside the plot area but not outside the chart, the mark line and the associated label will not be drawn (which is correct), but the mark tick is still drawn.
  
  
• The Center alignment for data labels is not correct in stacked bar charts if there are both positive and negative values in the same stacked bar.
  
  
• Layer.alignLayer has no effect in ChartDirector for ASP/COM/VB, PHP, Perl, Python, Ruby and C++..
  
  
• CColor in ChartDirector for ASP/COM/VB does not convert OLE colors to ChartDirector colors correctly.
  
  
• The font color argument in FinanceChart.setLegendStyle has no effect.

ChartDirector Ver 5.0 is designed to be code compatible with previous versions of ChartDirector. This means existing code should continue to work.

The charts produced by ChartDirector Ver 5.0 may be slightly different from the charts produced by earlier versions of ChartDirector. Please refer to Behaviour Changes in Ver 5.0 for details.

ChartDirector Ver 4.x licenses can upgrade to ChartDirector Ver 5.0 free of charge. ChartDirector Ver 5.0 automatically recognizes ChartDirector Ver 4.x license keys.

If you are using an earlier ChartDirector license (on the date of purchase, the ChartDirector version was Ver 3.x or below), you would need to purchase one or more upgrades to use ChartDirector Ver 5.x. Please refer to Purchasing ChartDirector Upgrade and Subscription for details.

To upgrade ChartDirector, simply install the new version on top of the old version.

For ChartDirector for ASP/COM/VB, you may need to run the installer twice to upgrade ChartDirector. When the installer it first run, it will detect the existing ChartDirector and uninstall it. If the existing ChartDirector is being used by another process (such as the IIS web server), the installer may prompt you to reboot in order to complete uninstallation. After uninstallation is completed, please run the installer again to install ChartDirector.

For the PHP/Perl/Python editions of ChartDirector, please remember to update the files "phpchartdir.php", "perlchartdir.pm" and "pychartdir.py". These files are the language interfaces to ChartDirector. Their versions must match exactly with that of the ChartDirector DLL or shared object. Depending on how you installed your existing ChartDirector, these files might be copied to the default module directory of your language interpreter, and/or to various scripting directories in your computer. Please ensure you update all of them.

If you are using PHP or mod_perl with Apache, you may need to restart the Apache server for the upgraded ChartDirector to take effect.