FreeBSD Manual Pages
KPLOT(3) Library Functions Manual KPLOT(3) NAME kplot -- plotting library for Cairo LIBRARY library "libkplot" DESCRIPTION The kplot library plots 2d data and functions on Cairo drawing con- texts. The library usually works as follows. 1. 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 po- sitions, differing in that buckets linearly translate position re- quests into internal storage. Histograms map from a range of floating-point pair positions into internal storage. Buffers can- not 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 val- ues change. 2. Modify using data source's individual functions or the generic kdata_get(3). 3. Allocate plots with kplot_alloc(3). 4. 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. 5. Draw plots to Cairo contexts with kplot_draw(3). 6. 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. Numerical Precision 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 in- ternal counters. If a plot is handed non-normal numbers (infinite, subnormal, NaN), the entire coordinate pair is discarded from range/do- main 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 obvi- ously) 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 mar- gins 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 stan- dard 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. SEE ALSO kdata_array_alloc(3), kdata_array_fill(3), kdata_bucket_add(3), kdata_bucket_alloc(3), kdata_buffer_alloc(3), kdata_buffer_copy(3), kdata_destroy(3), kdata_get(3), kdata_hist_add(3), kdata_hist_alloc(3), kdata_mean_add(3), kdata_mean_alloc(3), kdata_pmfmean(3), kdata_pmfstddev(3), kdata_pmfvar(3), kdata_stddev_add(3), kdata_stddev_alloc(3), kdata_vector_alloc(3), kdata_vector_append(3), kdata_xmax(3), kdata_xmean(3), kdata_xmin(3), kdata_xstddev(3), kdata_ymax(3), kdata_ymean(3), kdata_ymin(3), kdata_ystddev(3), kdatacfg_defaults(3), kplot_alloc(3), kplot_attach_data(3), kplot_attach_datas(3), kplot_attach_smooth(3), kplot_detach(3), kplot_draw(3), kplot_free(3), kplot_get_datacfg(3), kplot_get_plotcfg(3), kplotcfg_defaults(3) FreeBSD ports 15.quarterly March 24, 2015 KPLOT(3)
NAME | LIBRARY | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=kplot&sektion=3&manpath=FreeBSD+Ports+15.0.quarterly>