ADW-Charting - simple chart drawing with Common Lisp

ADW-Charting is a library that provides a simple interface to the Vecto vector drawing library. It supports drawing on a canvas and saving the results to a PNG file. The API was designed to eliminate as many decisions as possible, and simply produce a reasonable result with minimal fuss. It tries to scale various elements of the chart to fit nicely, but sometimes this goes awry.

ADW-Charting depends on the following libraries:

• Vecto

The easiest way to install ADW-Charting and all its dependencies is ASDF-Install

ADW-Charting's function interface is similar to Vecto's interface: you create charts by setting up a chart context and adding or setting information on that chart.

There are many known limitations at this point. We've got some plans on how to solve some of these, and other aren't priorities for me, and might stay around for ahwile.

• All colors are RGB, represented as a list of 3 numbers between 0 and 1, eg:'(1 .5 .3)
• The bounds on a pie chart are a bit goofy, as the radius of the pie is currently only determined by the height of the chart. This means a square image will cut off the legend.
• Another issue is with printing axis labels. There's some code to try to keep those reasonably spaces, but sometimes the labels start overlapping. Making the graph in two passes should let us calculate everything before starting to draw on the canvas, preventing this issue.
• The font used for all the text is included in the distribution, some random .ttf file pulled from the debian freefont library. You can specify the font file using the *default-font-file* unexported variable. I'm using a with-font macro internally that could solve this one.

Related libraries

• cl-plplot

All examples are available in test/examples.lisp in the distribution.

(with-pie-chart (300 200)
    (add-slice "A" 5.0d0)
    (add-slice "B" 2.0d0)
    (save-file "minimal-pie-chart.png"))

(with-line-chart (400 300)
    (add-series "A" '((-1 -2) (0 4) (1 5) (4 6) (5 -3)))
    (add-series "B" '((-1 4) (0 -2) (1 6) (5 -2) (6 5)))
    (save-file "minimal-line-chart.png"))

(with-line-chart (400 300 :background '(.7 .5 .7))
    (add-series "A" '((-1 -2) (0 4) (1 5) (4 6) (5 -3)))
    (add-series "B" '((-1 4) (0 -2) (1 6) (5 -2) (6 5)))
    (add-series "C"
		'((-1 0) (0 3) (1 1) (2 5) (4 -6))
		:color '(.3 .7 .9))
    (set-axis :y "widgets" :label-formatter "~,2F")
    (set-axis :x nil
	      :draw-gridlines-p nil
	      :label-formatter #'(lambda (v)
                                   ;;could do something more interesting here
				   (format nil "#~a" (floor v))))
    (save-file "customized-line-chart.png"))

The following symbols are exported from the ADW-CHARTING package.

Evaluates body with a chart established with the specified dimensions as the target for chart commands, with the specified background.

Adds a slice to the chart, with an optional color. A color will be automatically assigned if none is specified.

Evaluates body with a chart established with the specified dimensions as the target for chart commands, with the specified background.

Add another series to the line chart. data is a list of (x y) pairs. A color will be automatically assigned if none is specified.

Sets the axis on the current line chart. axis must be either :x or :y. The label-formatter must be either a format control string or a function of 1 argument that returns a string with the desired axis label.

Draws the chart as a png file to the given path.

Thanks to:

• Zach Beane for creating Vecto
• Peter Seibel for his excellent book, Practical Common Lisp
• Edi Weitz and Zach Beane for providing good examples on how to write and document lisp libraries
• Co-workers Nathan, Russ, and Rebecca for advice and code reviews

If you have any questions, comments, bug reports, or other feedback regarding ADW-Charting, please email Ryan Davis