Subversion Repositories cheapmusic

This is the NEWS file for PHPlot, with release documentation.

The project web site is http://sourceforge.net/projects/phplot/

The project home page is http://phplot.sourceforge.net/

Refer the the ChangeLog file for detailed source changes.

See NEWS_part1.txt for older release documentation.

-----------------------------------------------------------------------------

2015-11-01 Release 6.2.0

=== Overview:

This is the current stable release of PHPlot. This is the first release

that will work with the upcoming PHP-7. This release also adds two new plot

types.

The PHPlot Reference Manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

PHP-7 deprecated use of older-style class constructor method names, where

the constructor name matches the class name.  The PHPlot class constructor

name in this release has been fixed to work with PHP-7. This release

also works with PHP-5.4, 5.5, and 5.6. However, there is a compatibility

issue with extended classes. This applies even if you are using PHP-5.

If you define a class which extends the PHPlot class, you must use this

syntax to call the PHPlot constructor from your class constructor:

     parent::__construct(...);  // Call parent class constructor

This syntax also works in previous releases of PHPlot. However, the

following syntax also worked in older releases, and will no longer work:

     $this->PHPlot(...);  // Do Not Use This to call parent class constructor

or:  parent::PHPlot(...); // Do Not Use This Either

You must use the correct syntax parent::__construct() even if using PHP-5.

If you are using PHP-7 with PHPlot, here are a few other items to be aware of.

(Some of these affected the PHPlot test suite.)

+ PHPlot uses is_numeric() to check for missing points in the data array.

Starting with PHP-7, hexadecimal strings are no longer considered numeric.

This means if your data array contains the string "0x10", for example, PHPlot

will consider that to be the number 16 when using PHP-5.x, but will treat it

as a missing point with PHP-7. (Unquoted hexadecimal values are still numbers.)

+ PHP-7 no longer allows multiple function parameters with the same name.

A typical case which fails in PHP-7 is:

       function myfunction($s, $unused, $unused);  // Fails in PHP-7

This broke some PHPlot Test Suite scripts that implemented PHPlot callbacks

with unused parameters.

+ New objects cannot be assigned by reference. Very old versions of the

PHPlot Reference Manual had this syntax (and there may still be some old

versions out there):

        $plot =& new PHPlot(600, 400);  // Do not use &

+ Division by zero no longer results in E_WARNING, but you end up with one

of the special float values +INF, -INF, or NAN instead.

=== Bugs Fixed in 6.2.0:

Fixed bug #170 "replace eval() ...":

This was a request to remove use of eval() from SetDashedStyle(), because

eval() makes people nervous about security, and is not supported by some

Virtual Machines. Removed eval() by using a string template instead of a

code string for the dashed line pattern. There are no changes in usage or

behavior.

Fixed bug #172 "Fixes for PHP7":

This release now works with PHP-7 (currently pre-release). The constructor

name was changed; there were no problems with the rest of the code.

(Although several scripts in the PHPlot Test Suite also had to be fixed.)

Any class that extends PHPlot must now use the correct syntax to call the

parent constructor: parent::__construct(...). If they used the old syntax

$this->PHPlot(...) they will not work (even with PHP-5.x).

=== New features in 6.2.0:

Feature Request #55 "Method documentation in PHPDoc format":

PHPlot now uses "phpdoc"-style comments in the code, which apparently is

supported by some editors/IDEs. Note that the PHPlot Reference Manual does

currently make use of these comments.

Feature Request #56 "Hidden Y values when zero":

The request was for a way to hide Y label values when zero, but the

implementation is much more general. When using 'printf' label formatting

type, you can now specify 1, 2, or 3 separate format strings. These are

applied in the same way spreadsheets support cell format strings: which

format is used depends on the sign of the value.

Feature Request #57 "squarefilled plot type":

Two new plot types are added: 'squaredarea' and 'stackedsquaredarea'.

These are like area and stackedarea, but the edges are stepped like

'squared' plots.

Feature Request #58 "Data borders for area plot types":

After data borders support was added to the two new plot types 'squaredarea'

and 'stackedsquaredarea', this was extended to the existing, similar plot

types 'area' and 'stackedarea'. Data borders are off by default for all 4

plot types.

-----------------------------------------------------------------------------

2013-05-11 Release 6.1.0

=== Overview:

This is the current stable release of PHPlot. This release includes two new

plot type features (which were not completed in time to make it into

PHPlot-6.0.0).

The PHPlot Reference Manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

There are no new compatibility issues in this release. However, if

upgrading from PHPlot-5.8.0 or older, please read the Cautions, Important

Notes, and Compatibility Issues from the PHPlot-6.0.0 release. Everything

there is still applicable.

=== Bugs Fixed in 6.1.0:

(none)

=== New features in 6.1.0:

Feature Request #47 "Extend horizontal plots to more types":

This feature request was mostly implemented in PHPlot-6.0.0, except for

horizontal error plots, which are now implemented. A new data type

'data-data-yx-error' is used for horizontal error plots of type lines,

points, and linepoints.

Feature request #52 "Box Plots":

A new plot type 'boxes' is added. This produces a Box Plot, which is used

to present a 5-number statistical summary of a data set.

-----------------------------------------------------------------------------

2013-04-03 Release 6.0.0

=== Overview:

This is the current stable release of PHPlot. This release includes a

significant rewrite how PHPlot automatically calculates the plot area range

and tick increments from the data points. A number of new features and bug

fixes are also included.

The PHPlot Reference Manual has been updated to match this release. A

previously-experimental feature to help create HTML image maps is now

fully documented in the manual.

=== Cautions, Important Notes, and Compatibility Issues:

There are some important compatibility issues you need to be aware of

before upgrading to PHPlot-6.0.0 from any previous version. Many scripts

will produce different-looking plots with PHPlot-6.0.0 compared to earlier

versions. This is mostly due to changes in the automatic plot range and

tick increment calculations. Also, some scripts may fail, if they access

PHPlot class internal variables (properties) which have been changed to

have 'protected' visibility. See the details below.

+ Plot range calculations changed

PHPlot-6.0.0 uses a completely new method to calculate each of the 4 limits

of the plot area which are not defined using SetPlotAreaWorld(). As a

result, most plots that don't use SetPlotAreaWorld() with all 4 coordinates

given will look different under PHPlot-6.0.0. The two most notable changes

are that PHPlot-6.0.0 will usually stretch the range to include zero (if

the range does not already include zero), and under most conditions will

ensure that the X axis and Y axis both start and end at a tick mark position

(even if tick marks and labels are not visible). See bug #101 below.

+ Tick increment calculations changed

PHPlot-6.0.0 uses a completely new method to calculate tick increments

along the X axis and Y axis. This only occurs if the tick increments have

not been set using SetXTickIncrement() or SetNumXTicks() for X, and

SetYTickIncrement() or SetNumXTicks() for Y. If you let PHPlot calculate

the tick increments, your plot will likely have fewer or more tick

intervals than before, and the tick increment will be different. In

general, PHPlot-6.0.0 makes much better choices for tick increment.

See bug #132 below.

+ Class variable visibility changed

Most PHPlot class variables now have 'protected' visibility, so they are no

longer accessible from scripts that use the class. If your script directly

accesses PHPlot class variables - other than those documented in the manual

for 'tuning' - your script will not work with PHPlot-6.0.0. This change was

necessary because some internal class variables change in each PHPlot release,

and it is impossible to maintain compatibility with direct access to all these

class variables. If your script breaks because of variable visibility changes,

please: (1) see if you can use a public PHPlot class function instead, or

(2) post a message to the PHPlot help forum explaining why you need access to

a particular class variable.

+ SetPlotAreaWorld() now validates arguments

Starting with PHPlot-6.0.0, the SetPlotAreaWorld() function checks non-NULL

arguments for validity. For both X and Y, it is required that min < max if

both are specified. If you have a script that calls SetPlotAreaWorld() with

max <= min for either X or Y, that script will now fail. On the other hand,

some valid cases where you specify only one end of a range would previously

fail and now work.

+ SetRGBArray() now validates argument

If you use SetRGBArray() to load a custom color map but pass an invalid

argument (not an array or one of the known keywords), PHPlot will now fail

with an error message. In previous releases, a default black/white color

map was loaded in that case, with no error reported.

+ Removed order dependency: number of ticks and tick increment

If you want to control the tick increments (rather than letting PHPlot

calculate them), you should set either the number of ticks (SetNumXTicks(),

SetNumYTicks()) or the tick increment (SetXTickIncrement(),

SetYTickIncrement()), but not both, for each axis.  If you do set both,

PHPlot-5.8.0 and earlier will use the last setting you made, and ignore the

other.  PHPlot-6.0.0 gives priority to the tick increment setting and

ignores the number of ticks, regardless of the order. (The new behavior is

consistent with the PHPlot design goal that you can use the various Set*()

functions in any order and get the same plot.)

=== Bugs Fixed in 6.0.0:

Fixed bug #101 Fix automatic Y range calculations":

PHPlot now calculates the Y (and X) ranges using a completely different

method, which is described in the manual. There are new functions to 'tune'

the algorithm used, and of course you can still set the range limits manually.

In most cases, PHPlot now makes much better choices for the plot range limits.

Fixed bug #132 "Improve tick interval calculations":

PHPlot now by default picks a tick increment which is 1, 2, or 5 times a

power of 10, for much more 'natural' results. There are alternate

algorithms for selecting a 'binary' (power of 2) or date/time-based tick

increment instead. Rather than simply dividing the plot range by 10, PHPlot

now selects a tick increment based on the above requirement and which

results in at least 8 (by default) tick intervals.  Of course, you can

still specify the tick increment(s) directly.

Fixed bug #164 "Calculated defaults applied to subsequent plots":

This has been fixed for the cases of grid visibility, X data label angle,

and label format. A new bug #168 was written for a remaining issue with

label position defaults. This only apples when creating multiple plots on a

single image (overlay or side-by-side).

Fixed bug #165 "Missing axis labels on some empty plots":

In some cases, X axis labels would be absent for a plot with an empty data

array. PHPlot will now draw the axis labels even when the data array is empty.

Fixed bug #166 "Legend, UsePointShapes, and shape='none'":

PHPlot will now fall back to using a point marker in the legend when doing

a linepoints plot with a dataset using 'none' as the point shape (rather

than doing no marker at all). This only applies with SetLegendUseShapes(True).

Fixed bug #167 "Fails to find a default font on Ubuntu":

Ubuntu (via Debian) changed the installation path for the TrueType font

that PHPlot used as a default, causing font selection to fail.  The new

font installation path has been added to the search list, and now PHPlot

can find the default TrueType font on Ubuntu.

=== New features in 6.0.0:

Feature request #29 "Finer control over plot element colors":

This was an open-ended feature request that is partially implemented and

now closed. New functions were added to control element colors. (Some other

functions were added in previous releases.) In PHPlot-6.0.0, these functions

were added: SetLegendBgColor() for legend background color;

SetLegendTextColor() for legend text color, and functions for pie chart

border colors (see feature request #46 below).

Feature request #45 "Control pie chart start angle":

Implemented with new functions SetPieStartAngle() and SetPieDirection().

The angle for the first segment, and the direction (clockwise or

counter-clockwise) can now be set for pie charts.

Feature request #46 "Control pie chart borders":

Implemented with new functions SetDrawPieBorders() and SetPieBorderColor().

Pie segment borders can now be on (default for unshaded) or off (default for

shaded), and the color can be set independent of other elements.

Feature request #47 "Extend horizontal plots to more types":

This is partially implemented. Horizontal lines, linepoints, and points plots

are now implemented. Error plot versions of those horizontal plot types are

not yet implemented, but will probably be in the next release 6.1.0 (with

the introduction of a new data type).

   Note: In implementing feature request #47, the code for 'error' and

   'non-error' versions of the 3 plot types above were merged. A side effect

   of this is that data value labels (the labels within the plot area,

   identifying the data value at each point) now work for error plots, if

   enabled.  However, the default label position at 90 degrees will be crossed

   by the positive error bar. To avoid this, you can use the tuning variable

   data_value_label_angle; for example setting it to 45 degrees.

Feature request #50 "Control legend colorbox borders":

Implemented with new function SetLegendColorboxBorders().  There are now 3

choices for the borders around color boxes in the legend: 1) use the 'text'

color (the default, and compatible with PHPlot-5.8.0 and older); 2) use

data border colors; and 3) disable the borders.

  Note: Along with the implementation of feature request #50, a new function

  SetDrawDataBorders() was added to control drawing the data borders on bars

  and stackedbars plots. This supports having the same style (borders with

  matching color, or no borders) on both the legend color boxes and the data

  bars. The default is backward compatible: borders on unshaded plots, and

  no borders on shaded plots.

Feature request #51 "Lines instead of colorboxes in legend":

Implemented with existing function SetLegendUseShapes().  PHPlot now has

the option of showing short line segments (with correct color and width) in

the legend, rather than color boxes. This applies to lines and squared

plots only.

-----------------------------------------------------------------------------

2012-04-06 Release 5.8.0

=== Overview:

This is the current stable release of PHPlot. This release adds several new

features, including the ability to generate "streaming plots" - a video

stream showing updated plot data.

The PHPlot Reference Manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

There are no known compatibility issues in upgrading from PHPlot-5.7.0 to

this release. For issues with previous releases, see below in this file.

=== Bugs Fixed in 5.8.0:

Fix bug #3506408 "Data Label Lines vs new plot types":

Data label lines do work with bubble plots. This is now documented. Data

label lines did not work well with OHLC plot types. This was never documented

to work, and is now disabled.

=== New features in 5.8.0:

Feature request #3488042 "Display only some data value labels":

Custom label formatting functions now have access to the data point row and

column for data value labels, and to the row for axis data labels. You can

now filter or modify labels based on their position in the data array.

Documentation was updated.

Feature request #3501500 "Looping plot section (updating plot data)":

PHPlot can now produce "streaming plots", with updating data presented as a

Motion-JPEG stream. Documentation has been added to the reference manual.

Feature request #3515519 "Support object serialize/unserialize":

You can now serialize and unserialize a PHPlot object, subject to some

minor restrictions. Details are in the PHPlot Reference Manual.

-----------------------------------------------------------------------------

2012-02-25 Release 5.7.0

=== Overview:

This is the current stable release of PHPlot. This release includes several

bug fixes, new color controls for labels, a new feature for application-level

error handling, and an experimental feature for creating plot image maps.

The PHPlot reference manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

This release includes a change in how the color is set for data value

labels. (These are the labels inside the plot area that identify the tops

of bars, for example.) This can change the color of some labels. See the

bug report "Wrong color for data value labels" below.

This release reverts a change from PHPlot-5.4.0 to stackedbars plots. It

affects plots with stacked bar segments of size 0 that are at the top or

end of a stack. Starting in PHPlot-5.4.0, a zero-size segment at the top or

end would result in a color 'cap' on the bar stack, using the data color of

the zero-size segment. In PHPlot-5.7.0 this has been fixed. This will

change the appearance of some stackedbars plots.  See the bug report "Top

dropshadow [sic] of stacked bars..."

=== Bugs Fixed in 5.7.0:

#3396931 "Top dropshadow of stacked bars is always the same color":

  PHPlot will no longer draw a color 'cap' at the top or end of a bar stack

  if the last segment has a 0 value. (The term 'dropshadow' isn't correct.)

  Drawing the color for zero-size segments started in PHPlot-5.4.0 as part of

  the fix for bug #3296884, but the behavior was unexpected, so it was reverted.

  In general, PHPlot will now ignore segments with size 0, and if a stack

  contains all 0 values it will not be drawn. (The exception is if the axis is

  moved.)

#3488064 "Pie label failures in locales with comma decimal":

  Two work-arounds are implemented for what is essentially a PHP problem with

  locales that use something other than a period (typically comma) for the

  decimal separator.  When formatting labels as type 'data', PHPlot loads the

  locale settings to get the separator characters, but now it resets ('unloads')

  the settings afterwards. This helps avoid an error seen in PHPlot-5.6.0 with

  pie chart labels, where an incidental conversion of the label to a string

  resulted in use of the comma separator, followed by PHP failing to convert

  the number back to floating point because of the comma.  The second

  work-around is to avoid the conversion to string, in the case where the pie

  label has a single value. Together, these work-arounds should prevent the

  problem, but this is an imperfect fix.

#3486834 "Wrong color for data value labels":

  PHPlot was using the 'title' color (SetTitleColor()) for data value labels,

  which was wrong, as the title color is for the 3 plot title strings. PHPlot

  will now use the general text color (SetTextColor()) for data value labels,

  same as tick labels and axis data labels. This will change the appearance

  of some plots. In order to help with the compatibility issue, 4 new

  functions are introduced to control the colors of individual label types:

  SetTickLabelColor(), SetPieLabelColor(), SetDataLabelColor(), and

  SetDataValueLabelColor(). The defaults have been set up to be compatible

  (except for data value labels). Details are in the PHPlot Reference Manual.

=== New features in 5.7.0:

#3442041 "Provide data for generating image maps":

  An experimental feature has been added to allow a callback function to

  process the coordinates of individual plotted data points. This is most

  useful for generating an HTML image map for the plot. Refer to the text

  file Imagemaps.txt included in the PHPlot release for details. Caution:

  This is an experimental feature. It is subject to change, and not yet

  documented in the reference manual.

#3481195 "Custom message image":

  A new function DrawMessage() has been implement for special cases where you

  need to display an image containing a message, rather than a plot. This

  extends the PHPlot error reporting mechanism, and is intended for

  application-level errors. More information and an example can be found

  in the PHPlot Reference Manual.

-----------------------------------------------------------------------------

2012-01-02 Release 5.6.0

=== Overview:

This is the current stable release of PHPlot. This release includes

significant changes to pie charts. There are new ways to label pie charts,

and PHPlot does a better job calculating the size and positioning the labels.

The PHPlot reference manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

Pie charts will change appearance when you upgrade to PHPlot-5.6.0 from any

previous release. This is due to changes resulting from bug #3403297,

described below. You may notice these changes:

1. The pie chart itself will usually be drawn larger, taking up more of

   the image. This may result in interference with a plot legend.

2. Pie chart labels will be closer to the edge of the pie, if you are letting

   the label positions default. If you are using SetLabelScalePosition() to

   set the label positions, the results may vary even more.

3. Text alignment on pie chart labels will change.

4. World Coordinates are now undefined with pie charts.

If you are producing pie charts with PHPlot, you should review the output

of your scripts before using PHPlot-5.6.0 in production. If the output is

not acceptable, one or more of these steps might help:

1. If pie charts are too large, and/or interfere with a legend, try moving the

   legend. Alternatively, use SetPlotAreaPixels() or SetMarginsPixels() to

   limit the plot area.  Note, however, that starting in this release PHPlot

   sizes the pie so the labels fit inside the plot area too. You can control

   this with SetPieAutoSize().

2.  If you want labels positioned just outside the pie chart, do not call

    SetLabelScalePosition(), or set the value to the default 0.5. If you want

    labels just inside the pie, use 0.49. If you want labels to be about

    half-way inside the pie, use 0.25. (In previous releases, PHPlot multiple

    the label scale position by 1.2 before using it to position the labels,

    but this was not documented.)

3.  Your pie chart script will report errors if you use GetDeviceXY(),

    SetLegendWorld(), or SetLegendPosition(...,..., 'world'). This is because

    these functions require world coordinates, and world coordinates are not

    defined for pie charts. (Previous releases did define a world coordinate

    space for pie charts, but the values were meaningless.)

=== Bugs Fixed in 5.6.0:

#3403297 Pie chart sizing and label issues:

In addition to the fixes listed here, new features were added as a result

of this bug fix (see New features below).

+ Use both width and height of the pie when calculating its maximum size.

  (The bug was that the pie diameter would be sized to fit in the smaller

  of the image width and height. But a shaded pie is oval, so when the width

  if the pie was sized to the height of the image, the pie was too small.)

+ Fixed the text alignment of pie labels so they extend more naturally

  away from the pie chart (if outside the pie). (Don't just use center/center

  alignment for all labels.)

+ Do not multiply the label scale position by 1.2 in the hope that this will

  prevent labels from overlapping the pie. Use the label scale position

  as intended, and take other measures to prevent label overlap (such as

  fixing the text alignment).

+ Label positions along the bottom of the pie are now adjusted to account for

  the pie shading depth.

+ Plot area borders now work with pie charts. Use SetPlotBorderType() to

  enable them. The default is not to draw borders.

=== New features in 5.6.0:

A number of new features were added as a result of bug #3403297, described

above. The new features are:

+ Use the new function SetPieLabelType() to select the type of pie labels

  to be displayed. Labels can show segment percentages, segment values,

  string labels, or any other value using a custom function.

+ SetPieLabelType() also allows control over formatting of pie labels,

  similar to the way X and Y tick and data labels can be formatted.

+ Plot labels can be suppressed with SetLabelScalePosition(0).

+ The aspect ratio of shaded pies can be controlled with a tuning variable

  $pie_diam_factor. The default remains 0.5, making the pie height equal to

  half its width.

#413925 Table of values:

This very old feature request was implemented by adding a new script to the

"contrib" directory.  The data_table.php script contains a function to draw

a simple table of values on a PHPlot image. Examples are provided.

-----------------------------------------------------------------------------

For older releases, see NEWS_part1.txt