More plots improvements

[drgrice1]

Improvements to the plots.pl macro.

The first objective of this pull request is to make the output of the JSXGraph and TikZ formats for the plots.pl macro more consistent. The intent is that JSXGraph will be the primary display mode used in HTML, and TikZ the display mode in hardcopy, and the two should produce images that are a close as possible to the same. These changes are summarized as follows:

• Switch the JSXGraph arrows used for curve end markers from type 4 to type 2, and tweak the TikZ arrows to match. The type 4 arrows look quite bad on curves in almost all cases. The problem is that the curve line goes all the way to the end of the arrow, and so with the really sharp arrow point of the type 4 arrow the curve can be seen sticking out past the end of the arrow. The type 2 arrows are a little better, although they still have some of the same problem. The JSXGraph documentation recommends using type 7 arrows for this reason, but those are just ugly.

• Tweak the sizes of marks (or points) for the two formats. Note that the line width is now taken into account for points. TikZ does this by default for marks on a curve, but now also does this for all points even those that don't belong to a curve. JSXGraph also now takes this into account.

• Open marks (open_circle, open_square, open_triangle, and open_diamond) are now implemented as the closed variant filled with white. That is how it was done already for JSXGraph, but it is now also done that way for TikZ. I have seen the same issue with TikZ that was seen with the JSXGraph format that led to doing this there. That is the curve poking into the open part of the mark.

• The JSXGraph output now has ticks as well as the grid just like the pgfplots images. The tick sizes for both formats were tweaked for consistency.

• The JSXGraph grid is now limited within the axes in the same way that the pgfplots grid is. Also, the JSXGraph format places the axes labels on the edges in the cases that pgfplots does so. Additiionally, the JSXGraph format no longer reserves additional space for an axis in the cases that the axis is not shown. This again is the same as what pgfplots does.

• Vector/slope fields in tikz are now drawn 2 dimensionally (i.e., via addplot instead of addplot3) for pgfplots. In order to get the entire field the slope field at each level is drawn. This also means that the slope field now correctly honors the ysteps setting. Furthermore, using addplot3 messes with the 2 dimensional axes. pgfplots automatically changes the way things are drawn as soon as addplot3 is called. One obvious issue is that tick labels on the axes are not drawn when this is done.

• The linestyle => 'none' setting now works differently. The previous approach was inconsistent between the two formats. It set only marks for TikZ, but didn't draw curves at all for JSXGraph. That means that marks would be drawn for TikZ, but nothing for JSXGraph. Also, if fill => 'self' was also set, then the fill would appear in TikZ, but still nothing in JSXGraph. So now only marks is not set for TikZ, and instead draw=none is set, and for JSXGraph the curve is drawn, but with strokeWidth: 0. So now if linestyle => 'none' is set, then no marks are shown (unless the marks option is also given) and that is consistent for both formats. If fill => 'self' is also set, then the fill appears for both formats, still with no curve drawn.

The second objective is to add some new features and improve the way the macro works. Those changes are as follows:

• Allow the grid to be shown without the axes. The plots.pl documentation does not indicate that hiding the axes also hides the grid, but it does. That is not desirable, and there are images in which one might want the grid without the axes.

• Add axis minor_grids option. If this is 1 (the default), then grid lines are shown at minor tick locations, and otherwise they are not. This allows having minor ticks without associated grid lines which is sometimes desirable. The minor option still is the number of minor ticks (and minor grid lines if minor_grids is 1) and its documentation is updated to state this (instead of saying it is the number of minor grid lines even though it really was both).

• Tick labels are now displayed with MathJax by default in the JSXGraph format. This can be disabled by setting the mathajx_tick_labels axes style option to 0.

• The way the add_label method should be called is changed. Instead of $plot->add_label($y, $y, label => $label, %options); use $plot->add_label($y, $y, $label, %options); The first way will still work, but the second is how it should be done. The $label argument which is the text of the label and is an essential argument for a label, should not be an optional parameter.

• Add a rounded_corners option to round the corners on images. This is a general option that is passed to the Plot method. To make this work well the framed TikZ package cannot be used anymore. Instead the pgfplots axes is drawn in a savebox. Then the axes dimensions can be obtained and used to fill the box (with the corners clipped if corners are rounded) before the save box is actually rendered, and then draw the boundary box (again with rounded corners if desired).

• Add the new axes style option axes_arrows_both to have arrows in both directions on the axes.

• Move the JSXGraph board setup into a JavaScript file. The macro just passes the options for the board to the JavaScript. This results in a much smaller footprint in the generated page HTML sent to the browser, particularly if multiple images are in one problem. In addition, more features can be added in the JavaScript without adding to that footprint (such as the code for displaying tick labels as fractions, mixed numbers, and scientific notation -- see below).

  The new JavaScript file and the jsxgraphcore.js file both have the defer attribute. The jsxgraphcore.js file should have been loaded deferred before.

• There are no font sizes corresponding to all of the basic TeX font size declarations except scriptsize and footnotesize. So 'tiny', 'small', 'normalsize', 'large', 'Large', 'huge', and 'Huge' are the available font sizes. The medium and giant sizes from before are marked as deprecated, but still work. normalsize replaces medium and Large replaces giant. The reason that scriptsize and footnotesize were not included is because there isn't really room between tiny (8) and small (10) in the JSXGraph translation of sizes to put anything in between. I suppose one could be added at size 9, but you can barely see the difference, and at such small sizes I am not sure it matters.

• Add an add_point method, and deprecate the add_stamp method. The points added by the add_point method are basically datasets consisting of a single point, but are drawn after everything else so that they appear on top.

• Vector/slope fields are drawn in the order that the author adds them to the plot. Previously they were drawn after everything else which was just wrong. That meant that if a curve was added to the plot after a vector field it would be drawn behind the vector field (barring the use of a layer), and that really should not be the case. This is also needed in the code to ensure that points are drawn after everything else, and the reuse the existing dataset drawing code.

• An invalid color name no longer causes the problem to fail to render. Furthermore, SVG color names can be used directly without being defined by the add_color method. See section 4.3 of the TeX xcolor package for a list of SVG color names (https://ctan.mirrors.hoobly.com/macros/latex/contrib/xcolor/xcolor.pdf). Those work for both TikZ and JSXGraph directly.

• Add layer and fill_layer options. This allows fill regions to be drawn on the axis background layer, and is a much better approach than using the axis_on_top option. Using the axis_on_top option results in the axis being on top of all curves and function graphs, and generally looks bad. In addition, the axis_on_top option is not implemented at all for the JSXGraph format. By using layers the fill can be drawn on the background and the curve on the foreground.

  Note that the "standard" layer set for the TikZ format is now different than the pgfplots default. The "axis tick labels" is after the "pre main" and "main" layers. This is consistent with where JSXGraph places them, and is better than what pgplots does. Axis tick labels are textual elements that should be in front of the things that are drawn, together with the "axis descriptions". On the other hand, the JSXGraph axis layer is adjusted to match the pgfplot axis layer, which is above the axis tick layer. Further adjustments may be needed, but for now this gives a rather consistent match up.

  I decided to leave the general layer option exposing all layers (we discussed turning that into a draw_on_background option only). Instead I tweaked the pgfplots standard layer and the JSXGrpah default layers to make them more consistent. Also, I saw another use where another layer is best. That is for vector/slope fields. Those should be drawn on the pre main layer so that the arrows are in front of the grid and axis lines, but behind other curves and textual components such as the tick labels and axis labels.

• The fill between fill regions are no longer deferred until after everything else is drawn. That causes unintended side effects. Particularly, it is inconsistent with how fill => 'self' is done. In that case the fill is done immediately. As a result if both a "self" fill and a "fill between" fill are used, then the "self" fill ends up behind the "fill between" fill regardless of the order the two are created. So this respects the order of creation which is the author's intended order. Note that to protect against this the names of datasets that have been created are tracked, and if an author attempts to fill between a dataset and another dataset that has not yet been created, then the fill is not created and a warning is issued.

• The documented default for the arrow_size option was 10. That was the default for the TikZ format, but the actual JSXGraph default was 8. The two formats certainly cannot use different defaults. So now the default is 8 for both formats and documented as such. Furthermore, with the mark size tweaks mentioned earlier, that default (and other size settings) are similar for both formats.

• Add tick_distance, tick_scale, and tick_scale_symbol options. The tick_distance and tick_scale options give more fine grained control over tick placement than the former tick_delta option. The tick_delta option is all but deprecated (but I did not say so). The tick_delta is the product of the tick_distance and the tick_scale. The point is that the tick_distance, tick_scale, and tick_scale_symbol can be used to do things such as having ticks at multiples of pi and labeled as such. For example, if tick_distance => 1 / 4, tick_scale => pi, and tick_scale_symbol => '\pi', then the ticks will be labeled 0.25\pi, 0.5\pi, 0.75\pi, \pi, etc., and of course these ticks will appear at those actual distances on the axis (the tick_delta will be pi / 4).

• Add axis tick_label_format option. This can be one of "decimal", "fraction", "mixed", or "scinot" (default is "decimal"). It should be clear what those values mean. Note that this works well with the above options. So with the example for those options above and tick_label_format => "fraction", the tick labels will be \frac{1}{4}\pi, \frac{1}{2}\pi, \frac{3}{4}\pi, \pi, etc.

• Add extra_js_code and extra_tikz_code options. These can be used to add extra JavaScript or TikZ code to draw things that are not covered by the macro directly. These are advanced options that should be used with care, only by those that really know what they are doing, and always both options used together to keep the JSXGraph and TikZ output formats the same.

• Fix a bug that prevented functions defined by Perl functions from appearing at all in the TikZ format.

• Some issues with the Plots::Data::function_string method were fixed.

  First the absolute value was not working. The issue is the the absolute value in a MathObject does not stringify as the abs function. Something like abs(x) stringifies as |x|. The function_string parsing approach cannot handle something like that. To fix this a new stringifyAbsAsFunction context flag was added, and if that flag is set for the context the absolute value stringifies as abs. So abs(x) stringifies as abs(x).

  In addition there are no JavaScript functions Math.ln, Math.arcsosh, or Math.arctanh. So those "tokens" were fixed with the correct JavaScript functions which are Math.log (which is the natural log), Math.acosh, and Math.atanh, respectively.

Note that the GD image format (the Plots::GD package) for the plots macro has been removed. That format shouldn't be used anyway as it generates low quality graphics (at least in its current form).

[drgrice1]

I forgot to mention that this is built on top of #1322.

[drgrice1]

I added another change to this.

I optimized the TikZ format when a draw and fill occur separately. This is accomplished using the spath3 TikZ library. To make this work all paths need to be named, and if a draw and fill are done separately, then the fill just uses the path from the draw so it does not need to be recomputed.

Additionally refactor multipaths to make the TikZ format much more efficient, as well as to make multipaths more versatile. Both the TikZ and JSXGraph formats are done differently now. They both join the paths in a completely different way that does not use the x transform (so the function_string x transform code is now never used in fact). Instead in TikZ the spath3 TikZ library is used and the paths are drawn individually, and then concatenated. For the JSXGraph format the paths are created individually and their data points concatenated to form a single curve. The result allows for more versatility since now paths do not need to end where the next path starts. The paths are connected by a line segment if needed. For JSXGraph this just works with the concatenation approach. For TikZ this has to be added. Note this actually happened before with the previous TikZ implementation, but not for the JSXGraph implementation. The most important thing is that with this implementation the time that it takes for TeX to run for multipaths is greatly reduced. For the example in the POD and the current TikZ code it takes about 3 seconds for TikZ to run, and the CPU usage is quite high. If the fill and draw are on different layers so that the fill and draw occur separately, it takes even longer. With the new code it takes about 1 second for either case and the CPU usage is much less. One reason for this is that the number of steps needed with the new approach (which is now per curve) is much less. Previously 500 steps were used (by default) for the entire curve. Now 30 (by default) are used for each curve. Note that this can now be optimized and steps set per curve.

There is also a new cycle option for multipaths. If cycly => 1 is set for a multipath, then a line segment will be inserted from the end of the last path to the start of the first in the case that the last path does not end at the start of the first, thus closing the path.