NAME

kplot — plotting library for Cairo

LIBRARY

library “libkplot”

DESCRIPTION

The kplot library plots 2d data and functions on Cairo drawing contexts. The library usually works as follows.

Allocate plot data sources with kdata_array_alloc(3), kdata_bucket_alloc(3), kdata_buffer_alloc(3), kdata_hist_alloc(3), kdata_mean_alloc(3), kdata_stddev_alloc(3), and kdata_vector_alloc(3). Arrays and buckets have integral pair positions, differing in that buckets linearly translate position requests into internal storage. Histograms map from a range of floating-point pair positions into internal storage. Buffers cannot be directly modified, and are instead copied from other sources. Mean and standard deviation sources attach to other sources and compute the mean and standard deviation as their values change.
Modify using data source's individual functions or the generic kdata_get(3).
Allocate plots with kplot_alloc(3).
Associated each plot data source with one or more plot using kplot_attach_data(3) kplot_attach_datas(3), or kplot_attach_smooth(3). Plot data sources are added by reference; thus, they may be referenced by multiple plots.
Draw plots to Cairo contexts with kplot_draw(3).
Free plots with kplot_free(3) and data sources with kdata_destroy(3).

Domain and Range

Each plot domain and range is extended to fit all of its data sources at the moment kplot_draw(3) is invoked.

Styles

Styles are applied to plots and when a plot data source is added to a plot. Thus, if one has a data source referenced by two separate plots, they may be styled in different ways.

All values in kplot are double-precision floating-point, though some (such as kdata_mean_alloc(3)) will use the size_t integral type for internal counters. If a plot is handed non-normal numbers (infinite, subnormal, NaN), the entire coordinate pair is discarded from range/domain calculation and plotting.

Drawing Model

There are two main components to the drawing model: the plot area and the buffer zone.

The plot area consists of the plotted curves and overlapping borders and axis tics. Each border centre is drawn at the graph edge, so half the border width will extend into the plot. (This is how Cairo draws its lines.) Moreover, tics, if facing inward, will also (and obviously) be part of the plot area.

The buffer zone consists of the other half of borders, outward-facing tics, tic labels, axis labels, and the margin. The vertical (left and right) margins define the space between the left-most (or right-most) vertical axis label point and the image edge, or if labels have been specified, the same for those labels. Similarly, the horizontal margins define the space beyond the top-most (or bottom-most) horizontal axis label point.

The space around the plot area for labels takes into account horizontal labels flowing into the vertical label space and vice versa.

Borders and tics are not considered when measuring the buffer zone. Thus, a margin of zero will directly abut the plot area.

Memory Model

kplot uses the usual libc memory functions for allocation. However, plot data sources are reference-counted to make sharing between plots easier. Thus, calling kdata_destroy(3) will dereference, only freeing when nobody references the source.

Statistics

The kplot library is not built for high-level statistics, but some primitive statistics may be collected from the underlying data sources: arithmetic mean via kdata_xmean(3) and kdata_ymean(3), population standard deviation via kdata_xstddev(3) and kdata_ystddev(3), and extrema via kdata_xmin(3), kdata_xmax(3), kdata_ymin(3) and kdata_ymax(3). If the data describes a probability mass function, the kdata_pmfmean(3), kdata_pmfstddev(3), and kdata_pmfvar(3) functions are also provided.