1notcurses_plot(3)                                            notcurses_plot(3)
2
3
4

NAME

6       notcurses_plot - high level widget for plotting
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              #define NCPLOT_OPTION_LABELTICKSD   0x0001u
12              #define NCPLOT_OPTION_EXPONENTIALD  0x0002u
13              #define NCPLOT_OPTION_VERTICALI     0x0004u
14              #define NCPLOT_OPTION_NODEGRADE     0x0008u
15              #define NCPLOT_OPTION_DETECTMAXONLY 0x0010u
16              #define NCPLOT_OPTION_PRINTSAMPLE   0x0020u
17
18              typedef struct ncplot_options {
19                // channels for the maximum and minimum levels.
20                // lerp across the domain between these two.
21                uint64_t maxchannels;
22                uint64_t minchannels;
23                // styling used for labels (NCPLOT_OPTION_LABELTICKSD)
24                uint16_t legendstyle;
25                // pass NCBLIT_DEFAULT maps to NCBLIT_8x1 (assuming
26                // UTF8) or NCBLIT_1x1 (in an ASCII environment)
27                ncblitter_e gridtype;
28                // independent variable can either be a contiguous range,
29                // or a finite set of keys. for a time range, say the
30                // previous hour sampled with second resolution, the
31                // independent variable would be the range [0..3600): 3600.
32                // if rangex is 0, it is dynamically set to the number
33                // of columns.
34                int rangex;
35                const char* title;   // optional title
36                uint64_t flags;      // bitfield over NCPLOT_OPTION_*
37              } ncplot_options;
38
39       struct ncuplot* ncuplot_create(struct ncplane* n, const ncplot_options*
40       opts, uint64_t miny, uint64_t maxy);
41
42       struct ncdplot* ncdplot_create(struct ncplane* n, const ncplot_options*
43       opts, double miny, double maxy);
44
45       struct ncplane* ncuplot_plane(struct ncuplot* n);
46
47       struct ncplane* ncdplot_plane(struct ncdplot* n);
48
49       int ncuplot_add_sample(struct ncuplot* n, uint64_t x, uint64_t y);
50
51       int ncdplot_add_sample(struct ncdplot* n, uint64_t x, double y);
52
53       int ncuplot_set_sample(struct ncuplot* n, uint64_t x, uint64_t y);
54
55       int ncdplot_set_sample(struct ncdplot* n, uint64_t x, double y);
56
57       int ncuplot_sample(const struct ncuplot* n, uint64_t x, uint64_t* y);
58
59       int ncdplot_sample(const struct ncdplot* n, uint64_t x, double* y);
60
61       void ncuplot_destroy(struct ncuplot* n);
62
63       void ncdplot_destroy(struct ncdplot* n);
64

DESCRIPTION

66       These functions support histograms.  The independent variable is always
67       an uint64_t.  The samples are either  uint64_ts  (ncuplot)  or  doubles
68       (ncdplot).   Only  a  window  over the samples is retained at any given
69       time, and this window can only move towards larger values of the  inde‐
70       pendent  variable.   The  window  is moved forward whenever an x larger
71       than the current window's maximum is supplied to add_sample or set_sam‐
72       ple.
73
74       add_sample  increments  the current value corresponding to this x by y.
75       set_sample replaces the current value corresponding to this x.
76
77       If rangex is 0, or larger than the bound  plane  will  support,  it  is
78       capped  to  the available space.  The domain can either be specified as
79       miny and maxy, or domain autodetection can be invoked via setting  both
80       to  0.   If  the domain is specified, samples outside the domain are an
81       error, and do not contribute to the plot.  Supplying  an  x  below  the
82       current window is an error, and has no effect.
83
84       More  granular  block  glyphs  means more resolution in your plots, but
85       they can be difficult to differentiate at small text  sizes.   Sextants
86       and  Braille allow for more resolution on the independent variable.  It
87       can be difficult to predict how the Braille glyphs will look in a given
88       font.
89
90       The  same ncplot_options struct can be used with all ncplot types.  The
91       flags field is a bitmask composed of:
92
93       · NCPLOT_OPTION_LABELTICKSD: Label dependent axis ticks
94
95       · NCPLOT_OPTION_EXPONENTIALD: Use an exponential dependent axis
96
97       · NCPLOT_OPTION_VERTICALI: Vertical independent axis
98
99       · NCPLOT_OPTION_NODEGRADE: Fail rather than degrade blitter
100
101       · NCPLOT_OPTION_DETECTMAXONLY: Detect only max domain, not min
102
103       · NCPLOT_OPTION_PRINTSAMPLE: Print the most recent sample
104
105       If NCPLOT_OPTION_LABELTICKSD or NCPLOT_OPTION_PRINTSAMPLE is  supplied,
106       the  legendstyle  field will be used to style the labels.  It is other‐
107       wise ignored.
108
109       The label is printed in the upper left, immediately to the right of the
110       topmost  axis  tick  (if NCPLOT_OPTION_LABELTICKSD was used).  The most
111       recent sample is printed opposite from the label along the  independent
112       axis (if NCPLOT_OPTION_PRINTSAMPLE was used).
113

NOTES

115       NCPLOT_OPTION_VERTICALI is not yet implemented.
116

RETURN VALUES

118       create will return an error if miny equals maxy, but they are non-zero.
119       It will also return an error if maxy < miny.  An invalid gridtype  will
120       result in an error.
121
122       plane returns the ncplane on which the plot is drawn.  It cannot fail.
123

SEE ALSO

125       notcurses(3), notcurses_plane(3), notcurses_visual(3)
126

AUTHORS

128       nick black <nickblack@linux.com>.
129
130
131
132                                    v2.2.3                   notcurses_plot(3)
Impressum