ChartDirector Ver 5.1 Release Notes
This document describes the enhancements and bug fixes in ChartDirector Ver 5.1 comparing
to ChartDirector Ver 5.0.2. For earlier versions of ChartDirector, please refer to the
release notes archive.
Enhancements in Ver 5.1
Behaviour Changes in Ver 5.1
Legacy Development Environments
Bug Fixes in Ver 5.1
Upgrade ConsiderationsEnhancements in Ver 5.1
Programmable Track Cursor
Programmable Track Cursor provides an extra "cursor" that tracks the mouse cursor. For
example, the track cursor can be programmed as a vertical line that moves with the mouse
cursor, in which the line will automatically snap to the nearest data point(s), and with
dots that highlights the data points.
Dynamic information can be displayed with the track cursor. For example, legend entries can be updated to display the data values under the track cursor. Floating labels can be added to the axes to show the position of the mouse cursor and/or the data points. Floating boxes can be added to display information about the data points.
The appearance of the track cursor, as well as the dynamic information displayed, are all programmable and customizable to ensure maximum flexibility. Programmable Track Cursor is supported in both desktop and web based applications.
Dynamic information can be displayed with the track cursor. For example, legend entries can be updated to display the data values under the track cursor. Floating labels can be added to the axes to show the position of the mouse cursor and/or the data points. Floating boxes can be added to display information about the data points.
The appearance of the track cursor, as well as the dynamic information displayed, are all programmable and customizable to ensure maximum flexibility. Programmable Track Cursor is supported in both desktop and web based applications.
3D Scatter Chart
In addition to 3D Surface Chart, ChartDirector Ver 5.1 supports plotting 3D data as
symbols in an XYZ plot region, with configurable elevation and rotation angles and
perspective effect. Multiple symbol groups of different colors and/or shapes can be
plotted in the same chart. To aid 3D visualization, ChartDirector supports adding drop
lines to connect the symbols to the xy-plane. The symbols can also be colored based on the
z-value.
Subpixel Text Rendering
ChartDirector Ver 5.1 supports rendering text using ClearType or other subpixel
technologies.
On a color LCD display, a pixel consists of 3 subpixels positioned side-by-side for the RGB colors. In subpixel text rendering, glyphs are anti-aliased at the subpixel level, which can result in a higher effective resolution than the pixel resolution. The end result is clearer anti-aliased text.
On a color LCD display, a pixel consists of 3 subpixels positioned side-by-side for the RGB colors. In subpixel text rendering, glyphs are anti-aliased at the subpixel level, which can result in a higher effective resolution than the pixel resolution. The end result is clearer anti-aliased text.
3D Spline Strips
For XY line layers, step line layers and trend layers with straight line segments,
ChartDirector has long supported rendering the layers in 3D, in which the line segments
become strips. The 3D effect is now extended to spline curves. Like other 3D curved
objects in ChartDirector, Phong lighting effect with configurable ambient, diffuse and
specular parameters can be used for the 3D spline curve.
Fast Line Mode
Consider plotting 500000 data points in a line chart in which the plot area is 1000 pixels
wide. On average, 500 data points will be plotted in each horizontal pixel position. What
is visible is just the "envelope" of the data. Although ChartDirector can plot the chart
directly, it would be a waste of CPU time.
The traditional solution is to aggregate the data first, before passing the data to ChartDirector. If the data come from a database, data aggregation can be achieved easily by modifying the SQL. This makes both charting and the database faster. If done correctly (eg. with min/max aggregation to obtain the envelope), the resulting chart will be virtually indistinguishable from directly plotting all the data points.
However, in some cases, the data cannot be easily aggregated. For example, the data may not be from a database, or the data may be unevenly distributed, with some of the data points sparse (and therefore do not need aggregation) and some of the data points dense. Furthermore, if tooltips or a track cursor is used, the values displayed will be that of the aggregated points, not the original data points.
To address the above issues, ChartDirector Ver 5.1 includes an algorithm to automatically remove data points in a line chart if necessary, so as to better match the pixel dimension of the plot area. It only removes data points if they are overly dense in a way that would not affect the "envelope" of the line, so it is hardly noticible. The remaining data points are a subset of the original data points, so tooltips or a track cursor will display the original values.
The traditional solution is to aggregate the data first, before passing the data to ChartDirector. If the data come from a database, data aggregation can be achieved easily by modifying the SQL. This makes both charting and the database faster. If done correctly (eg. with min/max aggregation to obtain the envelope), the resulting chart will be virtually indistinguishable from directly plotting all the data points.
However, in some cases, the data cannot be easily aggregated. For example, the data may not be from a database, or the data may be unevenly distributed, with some of the data points sparse (and therefore do not need aggregation) and some of the data points dense. Furthermore, if tooltips or a track cursor is used, the values displayed will be that of the aggregated points, not the original data points.
To address the above issues, ChartDirector Ver 5.1 includes an algorithm to automatically remove data points in a line chart if necessary, so as to better match the pixel dimension of the plot area. It only removes data points if they are overly dense in a way that would not affect the "envelope" of the line, so it is hardly noticible. The remaining data points are a subset of the original data points, so tooltips or a track cursor will display the original values.
Bidirectional Text Layout
In certain languages, characters should flow from right to left, while in other languages,
they should be from left to right. In general, a piece of text can contain both types of
characters. Bidirectional text layout automatically rearranges the characters and modifies
their shapes if necessary to respect their natural flow direction.
Bidirectional Text Layout has been supported in ChartDirector for .NET since Ver 4.1. This is now extended to all editions of ChartDirector.
Bidirectional Text Layout has been supported in ChartDirector for .NET since Ver 4.1. This is now extended to all editions of ChartDirector.
Boundary Contour
In previous version of ChartDirector, for a contour layer, a contour at z = N is defined
as all points at z = N. For example, the contour at z = 10 are the points at z = 10. These
points normally constitute lines. However, if there is an exactly flat region at z = 10,
the entire region will be the contour and will be colored using the contour color.
Whereas ChartDirector Ver 5.1 still supports the above definition of a contour, it defaults to defining a contour at z = N to be the boundary between z < N and z >= N, except for the highest contour in which case the contour is the boundary between z <= N and z > N. With this definition, if there is a flat region at z = N, the contour will be the boundary of the region.
Whereas ChartDirector Ver 5.1 still supports the above definition of a contour, it defaults to defining a contour at z = N to be the boundary between z < N and z >= N, except for the highest contour in which case the contour is the boundary between z <= N and z > N. With this definition, if there is a flat region at z = N, the contour will be the boundary of the region.
Contour Layer Z Clipping
In a contour layer, the input is the z value of a few points on the XY plane.
ChartDirector would then compute the z values of all points on the XY plane using
interpolation. If spline surface interpolation is used, it is possible some interpolated
values will be higher than the highest input value or lower than the lowest input value.
For example, consider a linear sequence of points with z values (1, 2, 3, 3, 2, 1). The spline interpolator would probably determine that the "peak" is in between the middle two points, and is higher than 3 (the highest input value).
In many applications, the above behaviour is desirable and not an issue. However, in some applications, certain z values may be unrealistic. For example, if the z value is relative humidity, it should be in between 0 and 100. The spline interpolator, not knowing the nature of the data, may generate z values outside that range. To address this issue, ChartDirector Ver 5.1 supports clipping of z values to a configurable range, so that the contour layer would only display suitable z values.
For example, consider a linear sequence of points with z values (1, 2, 3, 3, 2, 1). The spline interpolator would probably determine that the "peak" is in between the middle two points, and is higher than 3 (the highest input value).
In many applications, the above behaviour is desirable and not an issue. However, in some applications, certain z values may be unrealistic. For example, if the z value is relative humidity, it should be in between 0 and 100. The spline interpolator, not knowing the nature of the data, may generate z values outside that range. To address this issue, ChartDirector Ver 5.1 supports clipping of z values to a configurable range, so that the contour layer would only display suitable z values.
CDML Enhancements
The ChartDirector Mark Up Language has been extended to support the following features:
- Built-in Symbols
In addition to an image file, the <*img*> CDML tag can now refer to a ChartDirector built-in symbol. For example, it is now possible to include triangles pointing at various directions, stars, glass spheres, etc, as icons embedded in text without using image files. - Block margins and edge color
ChartDirector Ver 5.1 adds support of configuable margins and edge color for the <*block*> CDML tag.
Parameter Substitution and Formatting Enhancements
- Currency Formatting
In previous versions of ChartDirector, currency formatting is achieved by using a label format like "${value}", which puts the currency symbol in front of the data value. This works perfectly for non-negative values, but for negative values, the formatting result becomes something like "$-100", instead of "-$100". To address this issue, ChartDirector Ver 5.1 includes direct support for the currency symbol in the Parameter Substitution and Formatting syntax, such that the currency symbol will be inserted before the digits but after the negative sign if any. - Sub-second Formatting
New fields are introduced in date/time formatting to represent tenth of a second, hundredth of a second and millisecond. This eliminates the need to use parameter expressions to derive these values.
Built-in Zoom/Scroll Axis Synchronization
In previous versions of ChartDirector, the Zooming and Scrolling framework does not
automatically synchronize axis scales with the view port. The developer would need to
include code to set up the axis scales based on the position and size of the view port.
ChartDirector Ver 5.1 now includes built-in support for axis synchronization.
.NET Client Profile Support
In .NET 4.0, Microsoft introduces the .NET Client Profile framework, which is a subset of
the standard .NET framework for desktop applications. The standard ChartDirector for .NET
assembly contains code to support both ASP.NET and desktop applications. Because of this,
Visual Studio 2010 will refuse to include the standard ChartDirector for .NET assembly in
a .NET Client Profile project, even if the ASP.NET part is not actually used. Instead, the
Visual Studio project must be configured to target the standard .NET framework.
To allow ChartDirector to be used in .NET Client Profile projects, ChartDirector Ver 5.1 now includes special signed and non-signed editions of the ChartDirector assembly with the ASP.NET part removed.
To allow ChartDirector to be used in .NET Client Profile projects, ChartDirector Ver 5.1 now includes special signed and non-signed editions of the ChartDirector assembly with the ASP.NET part removed.
Behaviour Changes in Ver 5.1
ChartDirector Ver 5.1 is designed to be code compatible with previous versions of
ChartDirector. This means existing code should continue to run. However, the charts
produced may look different in the following ways.
Subpixel Text Rendering
ChartDirector Ver 5.1 defaults to using subpixel text rendering. Earlier versions of
ChartDirector default to using classical anti-alias for large and bold font sizes, and
gridding fitting or smaller font sizes. That means the text may look different.
To revert to the earlier behaviour, the following line can be appended to the license file:
To revert to the earlier behaviour, the following line can be appended to the license file:
@TextAA=CompatAntiAliasIf you are using the setLicenseCode API to set the license key instead of using a license file, you may append a newline character and then the above line to your license key.
Bidirectional Text Layout
Earlier versions of ChartDirector do not automatically perform bidirectional text layout
(except ChartDirector for .NET, which supports bidirectional text layout since Ver 4.1).
Some developers that need to support right to left languages may have rearranged the
characters before passing to ChartDirector.
As ChartDirector Ver 5.1 already supports bidirectional text layout, there is no need to rearrange the characters before passing to ChartDirector. If the characters are rearranged without glyph substitution (and therefore ChartDirector still sees the original characters, albeit in different order), ChartDirector may rearrange them again, resulting in unexpected output.
As ChartDirector Ver 5.1 already supports bidirectional text layout, there is no need to rearrange the characters before passing to ChartDirector. If the characters are rearranged without glyph substitution (and therefore ChartDirector still sees the original characters, albeit in different order), ChartDirector may rearrange them again, resulting in unexpected output.
Boundary Contour
ChartDirector Ver 5.1 defaults to treating a contour as the boundary between different
regions. Earlier versions of ChartDirector treat a contour as the collection of points at
exactly the contour level. The two method differs if there is a flat region at exactly the
contour level. With ChartDirector Ver 5.1, the contour will be at the boundary of the
region, while in eariler versions of ChartDirector, the contour will be the entire region.
Legacy Development Environments
ChartDirector Ver 5.1 no longer supports the following legacy development environments:
- ChartDirector for .NET no longer supports .NET 1.x. It now requires .NET 2.0 or above.
- ChartDirector for JSP/Java no longer supports Java 1.2 or 1.3. It now
requires Java 1.4 or above.
- As Microsoft has stopped suppporting the VB6 IDE since 2008, the VB6 sample code included in ChartDirector for ASP/COM/VB will no longer be updated. In other words, the VB6 sample code will be the same sample code that ships with ChartDirector Ver 5.0.2. Note that the other sample code in ChartDirector for ASP/COM/VB (ASP, VBScript and JScript) will continue to be updated and will include the latest ChartDirector features.
Bug Fixes
The followings are the list of bugs that are fixed in ChartDirector Ver 5.1.
- Drop shadow incorrect if the shadow offset is negative.
Using a negative shadow offset may cause ChartDirector for JSP/Java to throw an exception, and cause other editions of ChartDirector to render the shadow incorrectly. This has now been fixed. - Alignment in BaseChart.addTable is incorrect.
The alignment parameter in BaseChart.addTable does not align the table as expected. This has now been fixed. - Error in legend box horizontal layout with text wrapping.
For a legend box using horizontal layout, if the text in a legend entry is so long that it needs to be wrapped into multiple lines, ChartDirector may mistakenly insert additional empty lines in the legend box. This has now been fixed. - Zone colors containing two different line styles do not work in SVG.
If a line is configured to be partially dashed and partially solid using a zone color, the line will end up totally dashed if rendered in SVG. This has now been fixed. - Consecutive addition/substraction in parameter expression is not
evaluated correctly
For example, the parameter expression "{={value}+1-1}" may not be correctly evaluated. This has now been fixed. - SVG output incorrect for certain international characters.
ChartDirector SVG output should be UTF8 encoded. However, ChartDirector may not correct encode certain international characters to UTF8 in SVG, resulting in corrupted characters in the chart. This has now been fixed. - Area layer rendered incorrectly if the first data point is
NoValue.
- The zero surface in a 3D area layer misses a border line.
For a 3D area layer, the surface at y = 0 is visible if the data are negative. When ChartDirector render the zero surface, it misses one of the edge of the surface. This has now been fixed. - ChartDirector may crash if a spline curve contains points that are way
outside the chart.
Normally, ChartDirector will auto-scale the axis to ensure the data points are within the chart. However, if the developer explicitly configures the axis scale (eg. 0 to 100), but uses data points way outside of the axis scale (eg. 100000000000000000000), the data points can become way outside the chart and ChartDirector may crash. This has now been fixed. - PieChart.setExplodeGroup does not work correctly if the slices are
positioned in anti-clockwise direction.
- ChartDirector may crash if a polar chart is configured to use
polygonal grid lines, but the angular axis has no major tick (with means a polygon with no
vertex).
ChartDirector will use circular grid if the angular axis has less than 3 major ticks, as a polygon requires at least 3 vertices. - SurfaceChart crashes if there are 3 or more points but less than 2
distinct points
Defining a surface requires at least 3 points, so ChartDirector would not draw a surface with less than 3 points. However, if there are 3 or more points, but less than 2 distinct points (which is possible if some points are duplicated), ChartDirector may attempt to draw the surface and crash. This has now been fixed. - BaseChart.makeTmpFile in ChartDirector for Perl and Python does not
work on Windows Vista for CGI application the server is IIS, and "localhost" is used in
the URL.
To generate the temporary file name, which must be unique for each user of the web server, ChartDirector combines several environmental parameters. One of the parameters used is REMOTE_HOST, which should be the address of the browser as according to the CGI standard. However, on Vista IIS, if "localhost" is used, the server may report the REMOTE_HOST as "::1". As ":" is an illegal character for file names, the temporary file name created is invalid. This has now been fixed.
Upgrade Considerations
Code Compatibility
ChartDirector Ver 5.1 is designed to be code compatible with previous versions of
ChartDirector. This means existing code should continue to run.
Behavioural Compatibility
The charts produced by ChartDirector Ver 5.1 may be different from the charts produced by
earlier versions of ChartDirector. In particular, ChartDirector will now automatically use
bidirectional text layout for text containing right to left characters. Please refer to
Behaviour Changes in Ver 5.1 for details.
Legacy Development Environments
ChartDirector for .NET requires .NET 2.0 or above. ChartDirector for JSP/Java requires
Java 1.4 or above. Older versions of .NET or Java is no longer supported.
License Compatibility
ChartDirector Ver 4.x and later licenses can upgrade to ChartDirector Ver 5.x free of
charge. ChartDirector Ver 5.x 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.
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.
Upgrade Procedure
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.
Previous versions of ChartDirector for .NET are distributed with an executable installer. ChartDirector for .NET Ver 5.1 no longer needs an installer. Instead, it is distributed simply as a zip file. Multiple versions of ChartDirector for .NET can coexist on the same computer, which means you do not have to uninstall the earlier version. In Visual Studio, you may drag multiple versions of the ChartDirector for .NET controls onto the Visual Studio toolbox (you may put different versions in different tabs to avoid mixing them up). If you do want to uninstall the earlier version, you may go to "Control Panel", select "Programs and Features" (or "Add or Remove Programs" in XP), and uninstall ChartDirector for .NET.
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.
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.
Previous versions of ChartDirector for .NET are distributed with an executable installer. ChartDirector for .NET Ver 5.1 no longer needs an installer. Instead, it is distributed simply as a zip file. Multiple versions of ChartDirector for .NET can coexist on the same computer, which means you do not have to uninstall the earlier version. In Visual Studio, you may drag multiple versions of the ChartDirector for .NET controls onto the Visual Studio toolbox (you may put different versions in different tabs to avoid mixing them up). If you do want to uninstall the earlier version, you may go to "Control Panel", select "Programs and Features" (or "Add or Remove Programs" in XP), and uninstall ChartDirector for .NET.
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.